> 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/models.md).

# Models

## The AccessGroupCommonFields object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupCommonFields":{"title":"Access group common fields","description":"These are the fields common to the access group summary, details, POST, and PATCH.\n","type":"object","properties":{"name":{"type":"string","description":"All items have a name.  Command Centre makes one up for you if you omit it when creating\nan item.\n"},"description":{"type":"string"},"division":{"type":"object","description":"Mandatory when creating any access group.  In this example, we want the access group in\ndivision 352.\n"},"parent":{"type":"object","description":"A link to the group's parent.\n\nThis field is optional in a POST because unlike divisions, which must have a parent, an\naccess group can stand alone.  But should you wish it to be a member of another, link it\nhere.\n\nAn access group may be a member of only one other:  multiple inheritance is not possible.\n\nUse the blank string `\"\"` to clear a group's parent in a PATCH.\n"}}}}}}
```

## The AccessGroupSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupSummary":{"title":"Access group summary","description":"These are the fields in the access group summary.\n","allOf":[{"$ref":"#/components/schemas/AccessGroupCommonFields"},{"type":"object","properties":{"id":{"type":"string","description":"An alphanumeric identifier for this access group.  No API calls use access group\nIDs.\n","readOnly":true},"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"A link to an [access group detail](models#accessgroupdetail) object for this\naccess group.\n"},"notes":{"type":"string"},"cardholders":{"type":"object","readOnly":true,"description":"Following this link lists the group's [direct\nmemberships](access-groups#get-api-access_groups-id-cardholders).\n\nIn v8.00 you will receive this field along with the ID and href in an access\ngroup's details page whether or not you specified it in the fields parameter, but\nif you send the fields parameter to 8.10 you will only get what you asked for.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"}}}]},"AccessGroupCommonFields":{"title":"Access group common fields","description":"These are the fields common to the access group summary, details, POST, and PATCH.\n","type":"object","properties":{"name":{"type":"string","description":"All items have a name.  Command Centre makes one up for you if you omit it when creating\nan item.\n"},"description":{"type":"string"},"division":{"type":"object","description":"Mandatory when creating any access group.  In this example, we want the access group in\ndivision 352.\n"},"parent":{"type":"object","description":"A link to the group's parent.\n\nThis field is optional in a POST because unlike divisions, which must have a parent, an\naccess group can stand alone.  But should you wish it to be a member of another, link it\nhere.\n\nAn access group may be a member of only one other:  multiple inheritance is not possible.\n\nUse the blank string `\"\"` to clear a group's parent in a PATCH.\n"}}}}}}
```

## The AccessGroupWriteableFields object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupWriteableFields":{"title":"Access group writeable fields","description":"These are the fields common to the POST and PATCH.\n","allOf":[{"$ref":"#/components/schemas/AccessGroupCommonFields"},{"type":"object","properties":{"notes":{"type":"string"},"parent":{"type":"object","description":"A link to the group's parent.\n\nThis field is optional in a POST because unlike divisions, which must have a\nparent, an access group can stand alone.  But should you wish it to be a member of\nanother, link it here.\n\nAn access group may be a member of only one other:  multiple inheritance is not\npossible.\n\nUse the blank string `\"\"` to clear a group's parent in a PATCH.\n"},"membershipAutoRemoveExpired":{"type":"boolean","description":"If true, memberships will be removed when their `until` time passes.  If false,\nthey will remain on the cardholder, inactive.\n"},"membershipFromDefault":{"type":"string","description":"When a cardholder is granted membership of this access group without specifying a\n'from' time, this default will apply.  If left blank, such a membership will not\nhave a 'from' time.  It will be effective immediately, provided its 'until' time\nis blank or in the future.\n\nTo clear it, send the blank string `\"\"`.\n","format":"date-time"},"membershipUntilDefault":{"type":"string","description":"When a cardholder is granted membership of this access group without specifying an\n'until' time, this default will apply.  If blank, such a membership will not have\nan 'until' time.  It will be effective until removed.\n\nTo clear it, send the blank string `\"\"`.\n","format":"date-time"}}}]},"AccessGroupCommonFields":{"title":"Access group common fields","description":"These are the fields common to the access group summary, details, POST, and PATCH.\n","type":"object","properties":{"name":{"type":"string","description":"All items have a name.  Command Centre makes one up for you if you omit it when creating\nan item.\n"},"description":{"type":"string"},"division":{"type":"object","description":"Mandatory when creating any access group.  In this example, we want the access group in\ndivision 352.\n"},"parent":{"type":"object","description":"A link to the group's parent.\n\nThis field is optional in a POST because unlike divisions, which must have a parent, an\naccess group can stand alone.  But should you wish it to be a member of another, link it\nhere.\n\nAn access group may be a member of only one other:  multiple inheritance is not possible.\n\nUse the blank string `\"\"` to clear a group's parent in a PATCH.\n"}}}}}}
```

## The AccessGroupPDFs object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupPDFs":{"title":"Access group PDFs for GET/POST","description":"This is the list of PDFs on an access group.  All the members of the access group will be\nable to have values for the PDFs in this array.\n\nEach element contains the href of a PDF definition.  To build the POST body you can take\nthose from the PDFs controller or other API routes, or copy it from the\n`personalDataDefinitions` block of another access group.\n\nThe GET returns the names of the PDFs, but the POST will ignore them.  If you need to change\nthe name of a PDF, use the PDF controller.\n","properties":{"personalDataDefinitions":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Read-only.","type":"string","readOnly":true},"href":{"description":"The href of the definition of the PDF for the access group.","type":"string","format":"uri-reference"}}}}}}}}}
```

## The AccessGroupSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupSearch":{"title":"Access group search","description":"An array of access group summaries and a `next` link for more.\n","properties":{"results":{"type":"array","description":"An array of access group summaries.","items":{"$ref":"#/components/schemas/AccessGroupSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"AccessGroupSummary":{"title":"Access group summary","description":"These are the fields in the access group summary.\n","allOf":[{"$ref":"#/components/schemas/AccessGroupCommonFields"},{"type":"object","properties":{"id":{"type":"string","description":"An alphanumeric identifier for this access group.  No API calls use access group\nIDs.\n","readOnly":true},"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"A link to an [access group detail](models#accessgroupdetail) object for this\naccess group.\n"},"notes":{"type":"string"},"cardholders":{"type":"object","readOnly":true,"description":"Following this link lists the group's [direct\nmemberships](access-groups#get-api-access_groups-id-cardholders).\n\nIn v8.00 you will receive this field along with the ID and href in an access\ngroup's details page whether or not you specified it in the fields parameter, but\nif you send the fields parameter to 8.10 you will only get what you asked for.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"}}}]},"AccessGroupCommonFields":{"title":"Access group common fields","description":"These are the fields common to the access group summary, details, POST, and PATCH.\n","type":"object","properties":{"name":{"type":"string","description":"All items have a name.  Command Centre makes one up for you if you omit it when creating\nan item.\n"},"description":{"type":"string"},"division":{"type":"object","description":"Mandatory when creating any access group.  In this example, we want the access group in\ndivision 352.\n"},"parent":{"type":"object","description":"A link to the group's parent.\n\nThis field is optional in a POST because unlike divisions, which must have a parent, an\naccess group can stand alone.  But should you wish it to be a member of another, link it\nhere.\n\nAn access group may be a member of only one other:  multiple inheritance is not possible.\n\nUse the blank string `\"\"` to clear a group's parent in a PATCH.\n"}}}}}}
```

## The AccessGroupDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupDetail":{"title":"Access group detail","description":"[/api/access_groups/{id}](access-groups#get-api-access_groups-id-) returns one of\nthese.  In addition to the basic details, it lists the child groups, privileges, and access\nzones and Salto items to which the group grants access.\n\nThere are brief descriptions of those fields below.  If they fall short, the Configuration\nClient's online documentation is the authority, in particular the section 'Setting up Access\nGroups'.\n","allOf":[{"$ref":"#/components/schemas/AccessGroupSummary"},{"$ref":"#/components/schemas/AccessGroupPDFs"},{"type":"object","properties":{"children":{"type":"array","description":"Names and links for the groups that claim this one as a parent.  This array does not\ninclude the children's children.\n\n**Notice of breaking change**.  This field being present and empty when the group has\nno children is a break from the API's principle of omitting empty fields, and is\ntherefore a bug.  A future version of Command Centre will not return the `children`\narray if the group has no children.\n","items":{"type":"object","properties":{"href":{"description":"The href of the child access group.","type":"string","format":"uri-reference"},"name":{"description":"The name of the child access group.","type":"string"}}}},"visitor":{"description":"If true, members of an access group with the 'escortVisitors' privilege can\nescort members of this group through a door, provided both groups have access to the\nentry zone.\n\nA group with 'visitor' cannot also have 'escortVisitors', 'lockUnlockAccessZones', or\n'firstCardUnlock', because visitors are not allowed to do those things.\n\nNew to 8.40.\n","type":"boolean"},"escortVisitors":{"description":"If true, members of this group can escort members of a group with the 'visitor'\nprivilege through a door, provided both groups have access to the entry zone.\n\nA group cannot have both 'escortVisitors' and 'visitor'.\n\nNew to 8.40.\n","type":"boolean"},"lockUnlockAccessZones":{"description":"If true, members of this group can use a reader or terminal to change the access mode\nof this group's access zones.  They can do this by logging on, if the reader has a\nscreen and keypad, or by double-badging.\n\nA group cannot have both 'lockUnlockAccessZones' and 'visitor'.\n\nNew to 8.40.\n","type":"boolean"},"enterDuringLockdown":{"description":"If true, members of this group are not subject to lockdown restrictions when\nrequesting to enter its access zones.\n\nNew to 8.40.\n","type":"boolean"},"firstCardUnlock":{"description":"If true, members of this group will change an access zone from secure to free when\nentering it, unlocking all its doors.\n\nA group cannot have both 'firstCardUnlock' and 'visitor'.\n\nNew to 8.40.\n","type":"boolean"},"overrideAperioPrivacy":{"description":"Some Aperio locks have a 'privacy mode' button that room occupants can push when they\ndo not want anyone else coming in.  If this field is true, Aperio locks will ignore\nthat button when members of this group attempt to open them.\n\nThis field will not appear if your site is not licensed for Aperio.\n\nNew to 8.40.\n","type":"boolean"},"aperioOfflineAccess":{"description":"Aperio locks normally refuse to open when offline.  If this field is true, Aperio\nlocks that support it will make an exception for members of this group.\n\nObviously the lock needs to be online long enough to synchronise this setting and the\nmembers of the group before setting it will have an effect.\n\nThis field will not appear if your site is not licensed for Aperio.\n\nNew to 8.40.\n","type":"boolean"},"disarmAlarmZones":{"description":"If true, members of this group can use a reader or terminal to disarm the\ngroup's access zones' alarm zones, either by logging on or double-badging.\n\nNew to 8.40.\n","type":"boolean"},"armAlarmZones":{"description":"If true, members of this group can use a reader or terminal to arm the\ngroup's access zones' alarm zones.\n\nNew to 8.40.\n","type":"boolean"},"hvLfFenceZones":{"description":"If true, members of this group can use a reader or terminal to change the\ngroup's fence zones between 'high voltage' and 'low feel', which will in turn change\nthe exuberance of their energisers.  A group's fence zones are those that use the same\nalarm zones as the group's access zones.\n\nNew to 8.40.\n","type":"boolean"},"viewAlarms":{"description":"If true, members of this group can view alarms and inputs on remote arming\nterminals (\"RATs\") and HBUS terminals.\n\nNew to 8.40.\n","type":"boolean"},"shunt":{"description":"If true, members of this group can shunt (isolate) items using RATs and\nHBUS terminals.\n\nNew to 8.40.\n","type":"boolean"},"lockOutFenceZones":{"description":"If true, members of this group can lock out (de-energise, make safe) fence\nzones using RATs and HBUS terminals.  Like all other access group privileges, this\nonly works on the fence zones to which this group has access.\n\nNew to 8.40.\n","type":"boolean"},"cancelFenceZoneLockout":{"description":"Normally, only the cardholder who locked out a fence zone can cancel the lockout and\nre-energise the fence.  With this privilege, members of this group can\ncancel any lockout on the group's fence zones.\n\nNew to 8.40.\n","type":"boolean"},"ackAll":{"description":"If true, members of this group can acknowledge alarms at a RAT or HBUS\nterminal.\n\nAn access group cannot have both this privilege and 'ackBelowHigh'.\n\nNew to 8.40.\n","type":"boolean"},"ackBelowHigh":{"description":"If true, members of this group can acknowledge alarms at a RAT or HBUS\nterminal, provided the alarms are not at high, very high, or critical priority.\n\nAn access group cannot have both this privilege and 'ackAll'.\n\nNew to 8.40.\n","type":"boolean"},"selectAlarmZone":{"description":"If true, members of this group can choose from a list of the group's alarm zones when\nperforming overrides at RATs and HBUS terminals, rather than having it chosen for them\nby site configuration.\n\nA group can only have this privilege if it also has 'disarmAlarmZones' or\n'armAlarmZones'.  Without one of those there is no point in being able to select an\nalarm zone.\n\nNew to 8.40.\n","type":"boolean"},"armWhileAlarm":{"description":"Normally, a cardholder cannot arm an alarm zone if it has open unshunted inputs.\nWith this privilege, members of the group can force-arm the alarm zone from a RAT or\nHBUS terminal.  What happens then depends on an alarm zone setting.\n\nA group with this privilege will also have 'armAlarmZones' and will not have\n'armWhileActiveAlarm'.\n\nNew to 8.40.\n","type":"boolean"},"armWhileActiveAlarm":{"description":"Normally, a cardholder cannot arm an alarm zone when it has active alarms.  Members of\na group with this privilege can do so from an HBUS terminal, provided they also meet\nother criteria (detailed in the Configuration Client documentation).\n\nA group with this privilege will also have 'armAlarmZones' and will not have\n'armWhileAlarm'.\n\nNew to 8.40.\n","type":"boolean"},"isolateAlarmZones":{"description":"Members of a group with this privilege have the option of isolating open inputs from a\nRAT or HBUS terminal when they are preventing an alarm zone from arming.  Like all\nthese privileges, it only works for the alarm zones on the group's access zones.\n\nTo have this privilege, a group must also have 'armAlarmZones'.\n\nNew to 8.40.\n","type":"boolean"},"access":{"type":"array","readOnly":true,"items":{"type":"object","properties":{"accessZone":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"schedule":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"description":"Names and hrefs of the access zones to which this access group gives access, and the\nschedules that govern it.\n\nThis field is read-only:  you cannot yet change an access group's access via the API.\n\nYour operator needs 'View Schedules' to see schedule hrefs, and 'View Site', 'Edit\nSite', or 'Override' to see access zone hrefs.\n\nNew to 8.40.\n"},"saltoAccess":{"readOnly":true,"type":"array","description":"Types, names, and hrefs of the Salto doors and door groups (\"Salto Access Zones\") to\nwhich this access group gives access, and the schedules that govern it.\n\nWatch those definitions:  a 'Salto Access Zone' is a group of Salto doors, while\nCommand Centre's definition of an access zone is a space into which a cardholder moves\nafter passing through a door.\n\nTherefore if an access group gives access to a Salto Access Zone, it is giving access\nthrough any number of Salto doors.  If you don't have access to the Salto system\nitself you can see the Salto zone/door hierarchy in the Command Centre Configuration\nclient.\n\nNew to 8.40.\n","items":{"description":"Each element in the array contains three blocks:  the Salto item type, the item\nitself, and the controlling schedule.\n","type":"object","properties":{"saltoItemType":{"description":"This block tells you whether the Salto item is a Salto door or a Salto 'access\nzone'.\n","type":"object","properties":{"value":{"type":"string","enum":["saltoAccessZone","saltoDoor"]}}},"saltoItem":{"description":"The name and href of the Salto zone or Salto door to which this access group\ngives access.\n"},"schedule":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}}},"alarmZones":{"type":"array","items":{"type":"object","properties":{"alarmZone":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"description":"Names and hrefs of the alarm zones to which members of this access group have the\n20-odd management privileges listed above.\n\nEach connection between the access group and the alarm zone is in its own block called\n`alarmZone` to leave room for the addition of more fields later.\n\nAdded in 8.40.\n"}}}]},"AccessGroupSummary":{"title":"Access group summary","description":"These are the fields in the access group summary.\n","allOf":[{"$ref":"#/components/schemas/AccessGroupCommonFields"},{"type":"object","properties":{"id":{"type":"string","description":"An alphanumeric identifier for this access group.  No API calls use access group\nIDs.\n","readOnly":true},"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"A link to an [access group detail](models#accessgroupdetail) object for this\naccess group.\n"},"notes":{"type":"string"},"cardholders":{"type":"object","readOnly":true,"description":"Following this link lists the group's [direct\nmemberships](access-groups#get-api-access_groups-id-cardholders).\n\nIn v8.00 you will receive this field along with the ID and href in an access\ngroup's details page whether or not you specified it in the fields parameter, but\nif you send the fields parameter to 8.10 you will only get what you asked for.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"}}}]},"AccessGroupCommonFields":{"title":"Access group common fields","description":"These are the fields common to the access group summary, details, POST, and PATCH.\n","type":"object","properties":{"name":{"type":"string","description":"All items have a name.  Command Centre makes one up for you if you omit it when creating\nan item.\n"},"description":{"type":"string"},"division":{"type":"object","description":"Mandatory when creating any access group.  In this example, we want the access group in\ndivision 352.\n"},"parent":{"type":"object","description":"A link to the group's parent.\n\nThis field is optional in a POST because unlike divisions, which must have a parent, an\naccess group can stand alone.  But should you wish it to be a member of another, link it\nhere.\n\nAn access group may be a member of only one other:  multiple inheritance is not possible.\n\nUse the blank string `\"\"` to clear a group's parent in a PATCH.\n"}}},"AccessGroupPDFs":{"title":"Access group PDFs for GET/POST","description":"This is the list of PDFs on an access group.  All the members of the access group will be\nable to have values for the PDFs in this array.\n\nEach element contains the href of a PDF definition.  To build the POST body you can take\nthose from the PDFs controller or other API routes, or copy it from the\n`personalDataDefinitions` block of another access group.\n\nThe GET returns the names of the PDFs, but the POST will ignore them.  If you need to change\nthe name of a PDF, use the PDF controller.\n","properties":{"personalDataDefinitions":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Read-only.","type":"string","readOnly":true},"href":{"description":"The href of the definition of the PDF for the access group.","type":"string","format":"uri-reference"}}}}}}}}}
```

## The AccessGroupMembership object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessGroupMembership":{"title":"Access group membership","description":"Returned in an array by\n[/api/access_groups/{id}/cardholders](access-groups#get-api-access_groups-id-cardholders),\ncontaining cardholders who are direct members of a particular group.  The array does\nnot contain the group's child groups, or their cardholder members.\n\nEach item contains a cardholder and (possibly) two date-times.  The group membership is active\nif and only if the current time is between 'from' and 'until'.  If 'from' is absent, assume\nthe distant past.  If 'until' is absent, assume the far future.\n\nUse the href in the cardholder block to change the 'from' and 'until', or even the\ngroup, using [cardholder patch](cardholders#patch-api-cardholders-id-).\n\nEach also contains an href at the top level:  DELETE that to remove the membership.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this URL to remove the membership.  Do not specify this when creating or\nmodifying a cardholder.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"cardholder":{"type":"object","description":"The name and href of the member cardholder."},"from":{"type":"string","format":"time-stamp"},"until":{"type":"string","format":"time-stamp"}}}}}}
```

## The AccessZoneSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessZoneSummary":{"title":"Access zone summary","description":"`/api/access_zones` returns an array of these.  It is a subset of what you get from an\naccess zone's detail page linked as the href in this object.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [access zone detail](models#accesszonedetail) object for this access\nzone.  It is also Command Centre's identifier for this access zone:  use it whenever you\nneed to specify an access zone in REST operations.\n"},"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events to\nparticular access zones.\n"},"name":{"type":"string"}}}}}}
```

## The AccessZoneDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AccessZoneDetail":{"title":"Access zone detail","description":"[/api/access_zones/{id}](access-zones#get-api-access_zones-id-) returns one of these.\n\nAs well as the properties below, it contains a block called `doors`.  This is reserved for\nfuture development and its behaviour could change in later versions of Command Centre.\n","allOf":[{"$ref":"#/components/schemas/AccessZoneSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this Access Zone."},"doors":{"type":"array","description":"A list containing names of and links to the doors that control entry to this access zone.","items":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the link to the [door's detail](models#doordetail), which\ncontains a return link back to this page in either its `entryAccessZone` or\n`exitAccessZone` field.\n"}}}},"zoneCount":{"readOnly":true,"type":"integer","description":"The number of cardholders in the zone, according to its zone counting configuration.\n\nAn access zone's count is part of its state, so [all that reading](item-status)\napplies here too.  The authoritative source is the zone's hardware controller, so the\nREST server only has it if it is monitoring it for another reason.  If it is not, it\nreturns a zero.\n\nThat is why zone counts are not in the default set of fields.  You can ask for them\nusing the 'fields' parameter, but you risk receiving a zero, so the recommended way is\nto follow the Access Zone's 'updates' link with `fields=defaults,zoneCount` appended\nafter the appropriate query parameter separator.\n\nA zone count is correct iff the access zone is online:  the status flags must contain\none of 'secure', 'dualAuth', 'codeOrCard', or 'free'.  Even then, the zone count could\nbe a minute out of date (depending on a server property that determines how long a\nhardware item can be silent before the server calls it offline).\n"},"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"},"updates":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n","readOnly":true},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n","readOnly":true},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"commands":{"type":"object","readOnly":true,"description":"A block of commands, each represented by a block containing an href that accepts a\nPOST that will send an override to the access zone, changing its state.\n\nIt will be missing if your operator does not have a privilege that allows overriding\nthe access zone (examples of which are in the documentation for the POSTs).\n","properties":{"free":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - no PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"freeUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"freePin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"freePinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"secure":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - no PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"secureUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"securePin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"securePinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"codeOnly":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - no PIN' access mode until the next scheduled\nchange.\n","type":"string","format":"uri-reference"}}},"codeOnlyUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"codeOnlyPin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - PIN' access mode until the next scheduled\nchange.\n","type":"string","format":"uri-reference"}}},"codeOnlyPinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"dualAuth":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - no PIN' access mode until the next scheduled\nchange.\n","type":"string","format":"uri-reference"}}},"dualAuthUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"dualAuthPin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"dualAuthPinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"forgiveAntiPassback":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-forgive_anti_passback) to this\nto forgive anti-passback for all cardholders in the zone.\n","type":"string","format":"uri-reference"}}},"setZoneCount":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-set_zone_count) to this to set the\nzone's cardholder count.\n","type":"string","format":"uri-reference"}}},"lockDown":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-lock_down) to this to set the zone\ninto lockdown mode.\n","type":"string","format":"uri-reference"}}},"cancelLockDown":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-cancel_lock_down) to this to cancel\nlockdown on the zone, returning it to its scheduled mode.\n","type":"string","format":"uri-reference"}}},"cancel":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-cancel) to this to cancel an\nactive override on the zone, returning it to its scheduled mode.  This will\nnot affect a lockdown.\n","type":"string","format":"uri-reference"}}}}}}}]},"AccessZoneSummary":{"title":"Access zone summary","description":"`/api/access_zones` returns an array of these.  It is a subset of what you get from an\naccess zone's detail page linked as the href in this object.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [access zone detail](models#accesszonedetail) object for this access\nzone.  It is also Command Centre's identifier for this access zone:  use it whenever you\nneed to specify an access zone in REST operations.\n"},"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events to\nparticular access zones.\n"},"name":{"type":"string"}}}}}}
```

## The AlarmSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmSearch":{"title":"Alarm search","description":"An array of alarm summaries, and either a 'next' or an 'updates' link you should follow to\nretrieve more alarms.\n","type":"object","properties":{"alarms":{"type":"array","description":"An array of alarm summaries.","items":{"$ref":"#/components/schemas/AlarmSummary"}},"next":{"type":"object","description":"The link to the next page of alarms. Missing if you have retrieved all the current alarms.","properties":{"href":{"type":"string"}}},"updates":{"type":"object","description":"The link to follow to long-poll for alarm changes.  Missing if you have not yet retrieved all the current alarms.","properties":{"href":{"type":"string"}}}}},"AlarmSummary":{"title":"Alarm summary","description":"`/api/alarms` returns an array of these, and `/api/alarms/{id}` returns one with more fields.","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this alarm, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this alarm, unique to the site but not across sites.\nOnce allocated, an ID is not re-used except after totally resetting the server's state\nby restoring the database.\n"},"time":{"type":"string","description":"The time the alarm occurred."},"message":{"type":"string","description":"The alarm's message."},"source":{"type":"object","description":"The ID and href are new to 8.10.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the alarm's source item.\n"},"name":{"type":"string","description":"The name of the alarm's source item at the time of the event."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item."}}},"type":{"type":"string","description":"The name of this alarm's event type.\n\nDeprecated in favour of the `eventType` block.\n"},"eventType":{"type":"object","description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n"},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"state":{"type":"string","description":"The state of the alarm.  Alarms start at \"unacknowledged\".","enum":["unacknowledged","acknowledged","processed"]},"active":{"type":"boolean","description":"Alarms can be stateless or stateful.  Stateless alarm types are spikes:  an operator\ngetting their password wrong or a cardholder being denied at a door.  Stateful alarms\nhave a triggering event and a restoring event:  a door being forced open then closed, or\na service going offline then reappearing later.\n\nStateless alarms are always inactive:  `active` will be false.  Stateful alarms will\nhave `active` true between being raised and restored.\n\nAn operator cannot process (dismiss) an active alarm without the 'Force process'\nprivilege.\n"},"division":{"type":"object","description":"The division entity representing the division of the alarm. GET the href for full details.","properties":{"href":{"type":"string","format":"uri-reference"}}},"event":{"type":"object","description":"A block containing a link (\"href\") to the details page of this alarm's event.  Useful if\nyou want an alarm's related items.\n\nThis mirrors an event's `alarm` field, which comes the other way.\n\nAdded in 8.90.  Not returned by default - you need to ask for it using the `fields` query parameter.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the event page for this alarm.  GET it for the fields found on an event\nthat are not on an alarm.\n"}}},"notePresets":{"type":"array","items":{"type":"string"},"description":"Preset alarm notes to use for this specific alarm. Missing if the alarm does not have specific notes; in this case the client should fall back to the server defaults."},"view":{"type":"object","description":"POST an alarm update request JSON object to the href to indicate the operator has viewed\nthe alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"comment":{"type":"object","description":"POST an alarm update request JSON object to the href to place an arbitrary alarm note\nagainst the alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledge":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm. Missing if\nthe system has mandatory alarm notes on for this alarm, or if the alarm is already\nacknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledgeWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm and place an\nalarm note against it.  Missing if the alarm is already acknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"process":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm. Missing if the\nsystem has mandatory alarm notes on for this alarm.  Missing if the alarm cannot be\nprocessed (if it is active, for example).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"processWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm and place an\nalarm note against it.  Missing if the alarm cannot be processed (if it is active, for\nexample).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"forceProcess":{"type":"object","description":"POST an alarm update request JSON object to this href to process an active alarm.  Missing\nif the alarm is not active (in which case you will have `process` and `processWithComment`\nlinks instead).\n\nThis action can take a comment in the body.  In fact an explanation is recommended since\nforce-processing an alarm is unusual.\n","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The AlarmUpdates object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmUpdates":{"title":"Alarm updates","type":"object","properties":{"updates":{"type":"array","description":"An array of summaries of alarms created or modified since the previous call.","items":{"$ref":"#/components/schemas/AlarmSummary"}},"next":{"type":"object","description":"Follow this link to perform another long poll.","properties":{"href":{"type":"string"}}}}},"AlarmSummary":{"title":"Alarm summary","description":"`/api/alarms` returns an array of these, and `/api/alarms/{id}` returns one with more fields.","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this alarm, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this alarm, unique to the site but not across sites.\nOnce allocated, an ID is not re-used except after totally resetting the server's state\nby restoring the database.\n"},"time":{"type":"string","description":"The time the alarm occurred."},"message":{"type":"string","description":"The alarm's message."},"source":{"type":"object","description":"The ID and href are new to 8.10.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the alarm's source item.\n"},"name":{"type":"string","description":"The name of the alarm's source item at the time of the event."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item."}}},"type":{"type":"string","description":"The name of this alarm's event type.\n\nDeprecated in favour of the `eventType` block.\n"},"eventType":{"type":"object","description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n"},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"state":{"type":"string","description":"The state of the alarm.  Alarms start at \"unacknowledged\".","enum":["unacknowledged","acknowledged","processed"]},"active":{"type":"boolean","description":"Alarms can be stateless or stateful.  Stateless alarm types are spikes:  an operator\ngetting their password wrong or a cardholder being denied at a door.  Stateful alarms\nhave a triggering event and a restoring event:  a door being forced open then closed, or\na service going offline then reappearing later.\n\nStateless alarms are always inactive:  `active` will be false.  Stateful alarms will\nhave `active` true between being raised and restored.\n\nAn operator cannot process (dismiss) an active alarm without the 'Force process'\nprivilege.\n"},"division":{"type":"object","description":"The division entity representing the division of the alarm. GET the href for full details.","properties":{"href":{"type":"string","format":"uri-reference"}}},"event":{"type":"object","description":"A block containing a link (\"href\") to the details page of this alarm's event.  Useful if\nyou want an alarm's related items.\n\nThis mirrors an event's `alarm` field, which comes the other way.\n\nAdded in 8.90.  Not returned by default - you need to ask for it using the `fields` query parameter.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the event page for this alarm.  GET it for the fields found on an event\nthat are not on an alarm.\n"}}},"notePresets":{"type":"array","items":{"type":"string"},"description":"Preset alarm notes to use for this specific alarm. Missing if the alarm does not have specific notes; in this case the client should fall back to the server defaults."},"view":{"type":"object","description":"POST an alarm update request JSON object to the href to indicate the operator has viewed\nthe alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"comment":{"type":"object","description":"POST an alarm update request JSON object to the href to place an arbitrary alarm note\nagainst the alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledge":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm. Missing if\nthe system has mandatory alarm notes on for this alarm, or if the alarm is already\nacknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledgeWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm and place an\nalarm note against it.  Missing if the alarm is already acknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"process":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm. Missing if the\nsystem has mandatory alarm notes on for this alarm.  Missing if the alarm cannot be\nprocessed (if it is active, for example).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"processWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm and place an\nalarm note against it.  Missing if the alarm cannot be processed (if it is active, for\nexample).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"forceProcess":{"type":"object","description":"POST an alarm update request JSON object to this href to process an active alarm.  Missing\nif the alarm is not active (in which case you will have `process` and `processWithComment`\nlinks instead).\n\nThis action can take a comment in the body.  In fact an explanation is recommended since\nforce-processing an alarm is unusual.\n","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The AlarmSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmSummary":{"title":"Alarm summary","description":"`/api/alarms` returns an array of these, and `/api/alarms/{id}` returns one with more fields.","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this alarm, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this alarm, unique to the site but not across sites.\nOnce allocated, an ID is not re-used except after totally resetting the server's state\nby restoring the database.\n"},"time":{"type":"string","description":"The time the alarm occurred."},"message":{"type":"string","description":"The alarm's message."},"source":{"type":"object","description":"The ID and href are new to 8.10.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the alarm's source item.\n"},"name":{"type":"string","description":"The name of the alarm's source item at the time of the event."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item."}}},"type":{"type":"string","description":"The name of this alarm's event type.\n\nDeprecated in favour of the `eventType` block.\n"},"eventType":{"type":"object","description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n"},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"state":{"type":"string","description":"The state of the alarm.  Alarms start at \"unacknowledged\".","enum":["unacknowledged","acknowledged","processed"]},"active":{"type":"boolean","description":"Alarms can be stateless or stateful.  Stateless alarm types are spikes:  an operator\ngetting their password wrong or a cardholder being denied at a door.  Stateful alarms\nhave a triggering event and a restoring event:  a door being forced open then closed, or\na service going offline then reappearing later.\n\nStateless alarms are always inactive:  `active` will be false.  Stateful alarms will\nhave `active` true between being raised and restored.\n\nAn operator cannot process (dismiss) an active alarm without the 'Force process'\nprivilege.\n"},"division":{"type":"object","description":"The division entity representing the division of the alarm. GET the href for full details.","properties":{"href":{"type":"string","format":"uri-reference"}}},"event":{"type":"object","description":"A block containing a link (\"href\") to the details page of this alarm's event.  Useful if\nyou want an alarm's related items.\n\nThis mirrors an event's `alarm` field, which comes the other way.\n\nAdded in 8.90.  Not returned by default - you need to ask for it using the `fields` query parameter.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the event page for this alarm.  GET it for the fields found on an event\nthat are not on an alarm.\n"}}},"notePresets":{"type":"array","items":{"type":"string"},"description":"Preset alarm notes to use for this specific alarm. Missing if the alarm does not have specific notes; in this case the client should fall back to the server defaults."},"view":{"type":"object","description":"POST an alarm update request JSON object to the href to indicate the operator has viewed\nthe alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"comment":{"type":"object","description":"POST an alarm update request JSON object to the href to place an arbitrary alarm note\nagainst the alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledge":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm. Missing if\nthe system has mandatory alarm notes on for this alarm, or if the alarm is already\nacknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledgeWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm and place an\nalarm note against it.  Missing if the alarm is already acknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"process":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm. Missing if the\nsystem has mandatory alarm notes on for this alarm.  Missing if the alarm cannot be\nprocessed (if it is active, for example).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"processWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm and place an\nalarm note against it.  Missing if the alarm cannot be processed (if it is active, for\nexample).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"forceProcess":{"type":"object","description":"POST an alarm update request JSON object to this href to process an active alarm.  Missing\nif the alarm is not active (in which case you will have `process` and `processWithComment`\nlinks instead).\n\nThis action can take a comment in the body.  In fact an explanation is recommended since\nforce-processing an alarm is unusual.\n","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The AlarmDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmDetail":{"title":"Alarm detail","description":"[/api/alarms/{id}](alarms#get-api-alarms-id-) returns one of these.  It contains\neverything from the alarm summary results, plus some extra fields that are too expensive to\ncompute and return for large result sets.\n","allOf":[{"type":"object","properties":{"details":{"type":"string","description":"The full alarm details text.  This may be up to 2048 UTF-8 characters, each of which\ncould (theoretically) be four bytes long.\n"},"history":{"type":"array","description":"An array of alarm history entries.  Missing if there is no history.","items":{"$ref":"#/components/schemas/AlarmHistoryEntry"}},"instruction":{"type":"object","description":"GET the href it contains to retrieve the alarm instruction body inside an HTML document.\n\nIn 9.10 and later you can request the instruction's name using the query parameter\n`fields=instruction.name`.  If you want the href as well, add `,instruction.href`.\n\nMissing if there is no alarm instruction for this alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"}}},"cardholder":{"type":"object","description":"The cardholder entity associated with this alarm. GET the href for full details. Missing if this alarm does not have an associated cardholder.","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string","description":"In versions up to and including 8.10 this is the current name of the cardholder.\nIn 8.20 it is the name of the cardholder at the time of the event.\n"},"firstName":{"type":"string","description":"The current value of the firstName field of this cardholder.  Added in 8.20."},"lastName":{"type":"string","description":"The current value of the lastName field of this cardholder.  Added in 8.20."}}}}},{"$ref":"#/components/schemas/AlarmSummary"}]},"AlarmHistoryEntry":{"title":"Alarm history entry","type":"object","properties":{"time":{"type":"string","description":"The time the history entry was added."},"action":{"type":"string","description":"The type of the history entry.","enum":["legacy","comment","acknowledge","process","acknowledgeActive","escalated","viewed"]},"comment":{"type":"string","description":"The added comment, or a textual description of some occurrence related to the alarm."},"operator":{"type":"object","description":"The operator that created the history event."}}},"AlarmSummary":{"title":"Alarm summary","description":"`/api/alarms` returns an array of these, and `/api/alarms/{id}` returns one with more fields.","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this alarm, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this alarm, unique to the site but not across sites.\nOnce allocated, an ID is not re-used except after totally resetting the server's state\nby restoring the database.\n"},"time":{"type":"string","description":"The time the alarm occurred."},"message":{"type":"string","description":"The alarm's message."},"source":{"type":"object","description":"The ID and href are new to 8.10.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the alarm's source item.\n"},"name":{"type":"string","description":"The name of the alarm's source item at the time of the event."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item."}}},"type":{"type":"string","description":"The name of this alarm's event type.\n\nDeprecated in favour of the `eventType` block.\n"},"eventType":{"type":"object","description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n"},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"state":{"type":"string","description":"The state of the alarm.  Alarms start at \"unacknowledged\".","enum":["unacknowledged","acknowledged","processed"]},"active":{"type":"boolean","description":"Alarms can be stateless or stateful.  Stateless alarm types are spikes:  an operator\ngetting their password wrong or a cardholder being denied at a door.  Stateful alarms\nhave a triggering event and a restoring event:  a door being forced open then closed, or\na service going offline then reappearing later.\n\nStateless alarms are always inactive:  `active` will be false.  Stateful alarms will\nhave `active` true between being raised and restored.\n\nAn operator cannot process (dismiss) an active alarm without the 'Force process'\nprivilege.\n"},"division":{"type":"object","description":"The division entity representing the division of the alarm. GET the href for full details.","properties":{"href":{"type":"string","format":"uri-reference"}}},"event":{"type":"object","description":"A block containing a link (\"href\") to the details page of this alarm's event.  Useful if\nyou want an alarm's related items.\n\nThis mirrors an event's `alarm` field, which comes the other way.\n\nAdded in 8.90.  Not returned by default - you need to ask for it using the `fields` query parameter.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the event page for this alarm.  GET it for the fields found on an event\nthat are not on an alarm.\n"}}},"notePresets":{"type":"array","items":{"type":"string"},"description":"Preset alarm notes to use for this specific alarm. Missing if the alarm does not have specific notes; in this case the client should fall back to the server defaults."},"view":{"type":"object","description":"POST an alarm update request JSON object to the href to indicate the operator has viewed\nthe alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"comment":{"type":"object","description":"POST an alarm update request JSON object to the href to place an arbitrary alarm note\nagainst the alarm.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledge":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm. Missing if\nthe system has mandatory alarm notes on for this alarm, or if the alarm is already\nacknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"acknowledgeWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to acknowledge an alarm and place an\nalarm note against it.  Missing if the alarm is already acknowledged.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"process":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm. Missing if the\nsystem has mandatory alarm notes on for this alarm.  Missing if the alarm cannot be\nprocessed (if it is active, for example).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"processWithComment":{"type":"object","description":"POST an alarm update request JSON object to the href to process an alarm and place an\nalarm note against it.  Missing if the alarm cannot be processed (if it is active, for\nexample).\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"forceProcess":{"type":"object","description":"POST an alarm update request JSON object to this href to process an active alarm.  Missing\nif the alarm is not active (in which case you will have `process` and `processWithComment`\nlinks instead).\n\nThis action can take a comment in the body.  In fact an explanation is recommended since\nforce-processing an alarm is unusual.\n","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The AlarmHistoryEntry object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmHistoryEntry":{"title":"Alarm history entry","type":"object","properties":{"time":{"type":"string","description":"The time the history entry was added."},"action":{"type":"string","description":"The type of the history entry.","enum":["legacy","comment","acknowledge","process","acknowledgeActive","escalated","viewed"]},"comment":{"type":"string","description":"The added comment, or a textual description of some occurrence related to the alarm."},"operator":{"type":"object","description":"The operator that created the history event."}}}}}}
```

## The AlarmZoneSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmZoneSummary":{"title":"Alarm Zone summary","type":"object","properties":{"href":{"type":"string","description":"A link to an [alarm zone detail](models#alarmzonedetail) object for this alarm\nzone.  This is Command Centre's identifier for this alarm zone:  use it whenever you need\nto specify an alarm zone in REST operations.\n","format":"uri-reference"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events\nto particular alarm zones.\n"},"name":{"type":"string"}},"description":"`/api/alarm_zones` returns an array of these.  It is a subset of what you get from an\nalarm zone's detail page at `/api/alarm_zones/{id}` (linked as the href in this\nobject).\n"}}}}
```

## The AlarmZoneDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"AlarmZoneDetail":{"title":"Alarm Zone detail","description":"[/api/alarm_zones/{id}](alarm-zones#get-api-alarm_zones-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/AlarmZoneSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this Alarm Zone.","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"shortName":{"maxLength":16,"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"},"updates":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Follow the URL in the href inside this block to receive the item's current status,\nthen follow the `next` link in the results to long poll for changes to that status.\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You\nshould use that to request all the fields you need in the update.\n"},"statusFlags":{"type":"array","description":"The search and details pages do not return status flags by default, because an item's\nstatus is unknown until something is monitoring it.  If you want status flags on the\nsearch and details pages you must ask for them using the `fields` parameter, but our\nadvice is to monitor them using [status\nsubscriptions](items#status-subscriptions) if you are running 8.30 or later,\notherwise the item's `updates` link.  See the [item status](item-status)\nsection for a full description of how to stay up to date with item status, and this\nitem's introduction in the Operations section for what flags this item might return\nand what they mean.\n","items":{"type":"string"}},"connectedController":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n","format":"uri-reference"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the\n`source` parameter of [event filters](events#get-api-events) and in the body\nof [status subscriptions](items#status-subscriptions).\n"}},"description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n"},"commands":{"type":"object","properties":{"arm":{"type":"object","properties":{"href":{"type":"string","description":"[POST](alarm-zones#post-api-alarm_zones-id-arm) to this to arm this\nalarm zone until the next scheduled change.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"Armed","enum":["Armed","Set"]}}},"armUntil":{"type":"object","properties":{"href":{"type":"string","description":"[POST](alarm-zones#post-api-alarm_zones-id-arm) to this to arm this\nalarm zone for a fixed time.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"Armed","enum":["Armed","Set"]}}},"disarm":{"type":"object","properties":{"href":{"type":"string","description":"[POST](alarm-zones#post-api-alarm_zones-id-disarm) to this to disarm this\nalarm zone until the next scheduled change.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"Disarmed","enum":["Disarmed","Unset"]}}},"disarmUntil":{"type":"object","properties":{"href":{"type":"string","description":"[POST](alarm-zones#post-api-alarm_zones-id-disarm) to this to disarm this\nalarm zone for a fixed time.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"Disarmed","enum":["Disarmed","Unset"]}}},"user1":{"type":"object","properties":{"href":{"type":"string","description":"[POST](#path-Alarm-Zones/post/api/alarm_zones/{id}/user1) to this to set the\nalarm zone's state to user1 until the next scheduled change.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"User1"}}},"user1Until":{"type":"object","properties":{"href":{"type":"string","description":"[POST](#path-Alarm-Zones/post/api/alarm_zones/{id}/user1) to this to set the\nalarm zone's state to user1 for a fixed time.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"User1"}}},"user2":{"type":"object","properties":{"href":{"type":"string","description":"[POST](#path-Alarm-Zones/post/api/alarm_zones/{id}/user2) to this to set the\nalarm zone's state to user2 until the next scheduled change.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"User2"}}},"user2Until":{"type":"object","properties":{"href":{"type":"string","description":"[POST](#path-Alarm-Zones/post/api/alarm_zones/{id}/user2) to this to set the\nalarm zone's state to user2 for a fixed time.\n","format":"uri-reference"},"name":{"type":"string","description":"Because a site can configure different names for different alarm\nzone states, they appear here.\n","default":"User2"}}},"cancel":{"type":"object","properties":{"href":{"type":"string","description":"[POST](alarm-zones#post-api-alarm_zones-id-cancel) to this to cancel an\nactive override on the alarm zone, returning it to its scheduled mode.\n\nThis command will not be available if the alarm zone is not\ncontrolled by a schedule (because without a schedule the alarm zone\ndoes not have the concept of a 'normal' state).\n","format":"uri-reference"}}}},"description":"A block of commands, each represented by a block containing an href that\naccepts a POST that will send an override to the alarm zone, changing its\nstate.\n\nSee the section 'Understanding Alarm Zones' in the Configuration client help\nfor a description of alarm zone states.\n\nIt will be missing if your operator does not have a privilege that allows overriding\nthe alarm zone (examples of which are in the documentation for the POSTs).\n"}}}]},"AlarmZoneSummary":{"title":"Alarm Zone summary","type":"object","properties":{"href":{"type":"string","description":"A link to an [alarm zone detail](models#alarmzonedetail) object for this alarm\nzone.  This is Command Centre's identifier for this alarm zone:  use it whenever you need\nto specify an alarm zone in REST operations.\n","format":"uri-reference"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events\nto particular alarm zones.\n"},"name":{"type":"string"}},"description":"`/api/alarm_zones` returns an array of these.  It is a subset of what you get from an\nalarm zone's detail page at `/api/alarm_zones/{id}` (linked as the href in this\nobject).\n"}}}}
```

## The HexString object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The DESFireEncodingRequest object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DESFireEncodingRequest":{"type":"object","properties":{"csn":{"$ref":"#/components/schemas/HexString"},"cadFiles":{"type":"object","description":"Optional data read from CAD files, if present on the card.","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"reason":{"type":"string","maxLength":100}},"required":["csn"],"description":"- `csn`: Card serial number (UID).\n- `cadFiles`: Gallagher Application Directory file contents as hex. Required if CAD files exist on card.\n- `reason`: Reason for encoding, e.g. \"New card issuance\", \"Lost card replacement\". Optional.\n"},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The DESFireFile object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DESFireFile":{"type":"object","properties":{"id":{"type":"integer","description":"Index of the file within the application."},"data":{"$ref":"#/components/schemas/HexString"},"accessRights":{"$ref":"#/components/schemas/HexString"},"communicationMode":{"$ref":"#/components/schemas/HexString"}},"required":["data","accessRights"]},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The DESFireKey object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DESFireKey":{"type":"object","properties":{"id":{"type":"integer","description":"Index of the key."},"name":{"type":"string","description":"A description of the key.  Not used in encoding."},"data":{"$ref":"#/components/schemas/HexString"},"version":{"$ref":"#/components/schemas/HexString"}},"required":["data"]},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The DESFireApplication object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DESFireApplication":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/HexString","description":"Application ID in hex with leading `0x`."},"name":{"type":"string","description":"A description of the application.  Not used in encoding."},"keys":{"type":"array","description":"Map of key number or name to key details.","items":{"$ref":"#/components/schemas/DESFireKey"}},"keySettings1":{"$ref":"#/components/schemas/HexString"},"keySettings2":{"$ref":"#/components/schemas/HexString"},"files":{"type":"array","description":"Map of file number to file content/access rights.","items":{"$ref":"#/components/schemas/DESFireFile"}}},"required":["files"]},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"},"DESFireKey":{"type":"object","properties":{"id":{"type":"integer","description":"Index of the key."},"name":{"type":"string","description":"A description of the key.  Not used in encoding."},"data":{"$ref":"#/components/schemas/HexString"},"version":{"$ref":"#/components/schemas/HexString"}},"required":["data"]},"DESFireFile":{"type":"object","properties":{"id":{"type":"integer","description":"Index of the file within the application."},"data":{"$ref":"#/components/schemas/HexString"},"accessRights":{"$ref":"#/components/schemas/HexString"},"communicationMode":{"$ref":"#/components/schemas/HexString"}},"required":["data","accessRights"]}}}}
```

## The CallbackLink object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CallbackLink":{"type":"object","properties":{"href":{"type":"string","description":"Absolute or relative URL for callback invocation."}},"required":["href"]}}}}
```

## The CallbackLinks object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CallbackLinks":{"type":"object","properties":{"encodeCompleted":{"$ref":"#/components/schemas/CallbackLink"},"encodeFailed":{"$ref":"#/components/schemas/CallbackLink"}},"required":["encodeCompleted","encodeFailed"]},"CallbackLink":{"type":"object","properties":{"href":{"type":"string","description":"Absolute or relative URL for callback invocation."}},"required":["href"]}}}}
```

## The EncryptedEncodingData object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EncryptedEncodingData":{"type":"object","properties":{"cipherText":{"type":"string","description":"The encrypted encoding data, encoded as a base64 string."},"iv":{"type":"string","description":"The initialisation vector used for encryption, encoded as a base64 string."},"ephemeralPublicKey":{"type":"string","description":"The ephemeral public key used for encryption, encoded as a base64 string."},"tag":{"type":"string","description":"The authentication tag for the encrypted data, encoded as a base64 string."}},"required":["cipherText","iv","ephemeralPublicKey","tag"]}}}}
```

## The EncryptedEncodingDataResponseOrDecryptedForInfo object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EncryptedEncodingDataResponseOrDecryptedForInfo":{"title":"Encrypted response and its decrypted forms.","oneOf":[{"$ref":"#/components/schemas/EncryptedEncodingDataResponse"},{"$ref":"#/components/schemas/DecryptedDESFireDataForInfo"},{"$ref":"#/components/schemas/DecryptedClassicDataForInfo"}]},"EncryptedEncodingDataResponse":{"type":"object","title":"Response schema","properties":{"encryptedEncodingData":{"$ref":"#/components/schemas/EncryptedEncodingData"},"callback":{"$ref":"#/components/schemas/CallbackLinks"}},"required":["encryptedEncodingData","callback"]},"EncryptedEncodingData":{"type":"object","properties":{"cipherText":{"type":"string","description":"The encrypted encoding data, encoded as a base64 string."},"iv":{"type":"string","description":"The initialisation vector used for encryption, encoded as a base64 string."},"ephemeralPublicKey":{"type":"string","description":"The ephemeral public key used for encryption, encoded as a base64 string."},"tag":{"type":"string","description":"The authentication tag for the encrypted data, encoded as a base64 string."}},"required":["cipherText","iv","ephemeralPublicKey","tag"]},"CallbackLinks":{"type":"object","properties":{"encodeCompleted":{"$ref":"#/components/schemas/CallbackLink"},"encodeFailed":{"$ref":"#/components/schemas/CallbackLink"}},"required":["encodeCompleted","encodeFailed"]},"CallbackLink":{"type":"object","properties":{"href":{"type":"string","description":"Absolute or relative URL for callback invocation."}},"required":["href"]},"DecryptedDESFireDataForInfo":{"title":"Example DESFire card data after decryption","summary":"This is not actual API data.  It is for information only.","description":"This is not actual API data.  It is for information only.","type":"object","properties":{"cardMasterKey":{"$ref":"#/components/schemas/HexString"},"defaultAppKey":{"$ref":"#/components/schemas/HexString"},"applications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"name":{"type":"string"},"data":{"$ref":"#/components/schemas/HexString"},"version":{"type":"integer","minimum":1}}}},"keySettings1":{"type":"string"},"keySettings2":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"data":{"$ref":"#/components/schemas/HexString"},"accessRights":{"$ref":"#/components/schemas/HexString"},"communicationMode":{"$ref":"#/components/schemas/HexString"}}}}}}}}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"},"DecryptedClassicDataForInfo":{"title":"Example Classic card data after decryption","summary":"This is not actual API data.  It is for information only.","description":"This is not actual API data.  It is for information only.","type":"object","properties":{"sectors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"name":{"type":"string"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"file":{"$ref":"#/components/schemas/HexString"}}}}}}}}}}}}
```

## The EncryptedEncodingDataResponse object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EncryptedEncodingDataResponse":{"type":"object","title":"Response schema","properties":{"encryptedEncodingData":{"$ref":"#/components/schemas/EncryptedEncodingData"},"callback":{"$ref":"#/components/schemas/CallbackLinks"}},"required":["encryptedEncodingData","callback"]},"EncryptedEncodingData":{"type":"object","properties":{"cipherText":{"type":"string","description":"The encrypted encoding data, encoded as a base64 string."},"iv":{"type":"string","description":"The initialisation vector used for encryption, encoded as a base64 string."},"ephemeralPublicKey":{"type":"string","description":"The ephemeral public key used for encryption, encoded as a base64 string."},"tag":{"type":"string","description":"The authentication tag for the encrypted data, encoded as a base64 string."}},"required":["cipherText","iv","ephemeralPublicKey","tag"]},"CallbackLinks":{"type":"object","properties":{"encodeCompleted":{"$ref":"#/components/schemas/CallbackLink"},"encodeFailed":{"$ref":"#/components/schemas/CallbackLink"}},"required":["encodeCompleted","encodeFailed"]},"CallbackLink":{"type":"object","properties":{"href":{"type":"string","description":"Absolute or relative URL for callback invocation."}},"required":["href"]}}}}
```

## The DecryptedDESFireDataForInfo object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DecryptedDESFireDataForInfo":{"title":"Example DESFire card data after decryption","summary":"This is not actual API data.  It is for information only.","description":"This is not actual API data.  It is for information only.","type":"object","properties":{"cardMasterKey":{"$ref":"#/components/schemas/HexString"},"defaultAppKey":{"$ref":"#/components/schemas/HexString"},"applications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"name":{"type":"string"},"data":{"$ref":"#/components/schemas/HexString"},"version":{"type":"integer","minimum":1}}}},"keySettings1":{"type":"string"},"keySettings2":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"data":{"$ref":"#/components/schemas/HexString"},"accessRights":{"$ref":"#/components/schemas/HexString"},"communicationMode":{"$ref":"#/components/schemas/HexString"}}}}}}}}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The DecryptedClassicDataForInfo object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DecryptedClassicDataForInfo":{"title":"Example Classic card data after decryption","summary":"This is not actual API data.  It is for information only.","description":"This is not actual API data.  It is for information only.","type":"object","properties":{"sectors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"name":{"type":"string"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0},"file":{"$ref":"#/components/schemas/HexString"}}}}}}}}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The DESFireEncodingResponse object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DESFireEncodingResponse":{"type":"object","properties":{"applications":{"type":"array","description":"Map of application ID in hex with leading `0x` to application details.","items":{"$ref":"#/components/schemas/DESFireApplication"}},"cardMasterKey":{"type":"string","description":"The value of the AES key that the card's master key would be set to if encoded from Command Centre"},"defaultAppKey":{"type":"string","description":"The value that the card's default app key would be set to if encoded from Command Centre"}},"required":["applications"]},"DESFireApplication":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/HexString","description":"Application ID in hex with leading `0x`."},"name":{"type":"string","description":"A description of the application.  Not used in encoding."},"keys":{"type":"array","description":"Map of key number or name to key details.","items":{"$ref":"#/components/schemas/DESFireKey"}},"keySettings1":{"$ref":"#/components/schemas/HexString"},"keySettings2":{"$ref":"#/components/schemas/HexString"},"files":{"type":"array","description":"Map of file number to file content/access rights.","items":{"$ref":"#/components/schemas/DESFireFile"}}},"required":["files"]},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"},"DESFireKey":{"type":"object","properties":{"id":{"type":"integer","description":"Index of the key."},"name":{"type":"string","description":"A description of the key.  Not used in encoding."},"data":{"$ref":"#/components/schemas/HexString"},"version":{"$ref":"#/components/schemas/HexString"}},"required":["data"]},"DESFireFile":{"type":"object","properties":{"id":{"type":"integer","description":"Index of the file within the application."},"data":{"$ref":"#/components/schemas/HexString"},"accessRights":{"$ref":"#/components/schemas/HexString"},"communicationMode":{"$ref":"#/components/schemas/HexString"}},"required":["data","accessRights"]}}}}
```

## The ClassicBlocks object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ClassicBlocks":{"type":"object","description":"Map of block index to data block bytes.  The block is binary data in hex string format that\ncorresponds to a file in the sector.\n","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The ClassicCad object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ClassicCad":{"title":"MIFARE Classic CAD","type":"object","properties":{"sector":{"type":"integer"},"blocks":{"$ref":"#/components/schemas/ClassicBlocks"}},"required":["sector","blocks"]},"ClassicBlocks":{"type":"object","description":"Map of block index to data block bytes.  The block is binary data in hex string format that\ncorresponds to a file in the sector.\n","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The ClassicMad object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ClassicMad":{"title":"MIFARE Classic MAD","type":"object","properties":{"blocks":{"$ref":"#/components/schemas/ClassicBlocks"}},"required":["blocks"]},"ClassicBlocks":{"type":"object","description":"Map of block index to data block bytes.  The block is binary data in hex string format that\ncorresponds to a file in the sector.\n","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The ClassicEncodingRequest object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ClassicEncodingRequest":{"type":"object","properties":{"csn":{"$ref":"#/components/schemas/HexString"},"cad":{"$ref":"#/components/schemas/ClassicCad"},"mad":{"$ref":"#/components/schemas/ClassicMad"},"unavailableSectors":{"type":"array","items":{"type":"integer"}},"reason":{"type":"string","maxLength":100}},"required":["csn"],"description":"- `csn`: Card UID.\n- `cad`: Gallagher Application Directory sector/blocks (required if present on card).\n- `mad`: MAD bytes (required if present on card).\n- `unavailableSectors`: Sectors already occupied or reserved.\n- `reason`: Reason for encoding, e.g. \"New card issuance\", \"Lost card replacement\". Optional.\n"},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"},"ClassicCad":{"title":"MIFARE Classic CAD","type":"object","properties":{"sector":{"type":"integer"},"blocks":{"$ref":"#/components/schemas/ClassicBlocks"}},"required":["sector","blocks"]},"ClassicBlocks":{"type":"object","description":"Map of block index to data block bytes.  The block is binary data in hex string format that\ncorresponds to a file in the sector.\n","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"ClassicMad":{"title":"MIFARE Classic MAD","type":"object","properties":{"blocks":{"$ref":"#/components/schemas/ClassicBlocks"}},"required":["blocks"]}}}}
```

## The ClassicSector object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ClassicSector":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"integer"},"blocks":{"type":"array","description":"List of blocks in this sector to be encoded.","items":{"$ref":"#/components/schemas/ClassicBlocks"}}},"required":["blocks"]},"ClassicBlocks":{"type":"object","description":"Map of block index to data block bytes.  The block is binary data in hex string format that\ncorresponds to a file in the sector.\n","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The ClassicEncodingResponse object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ClassicEncodingResponse":{"type":"object","properties":{"sectors":{"type":"array","description":"Map of sector number to sector data/blocks.","items":{"$ref":"#/components/schemas/ClassicSector"}}},"required":["sectors"]},"ClassicSector":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"integer"},"blocks":{"type":"array","description":"List of blocks in this sector to be encoded.","items":{"$ref":"#/components/schemas/ClassicBlocks"}}},"required":["blocks"]},"ClassicBlocks":{"type":"object","description":"Map of block index to data block bytes.  The block is binary data in hex string format that\ncorresponds to a file in the sector.\n","additionalProperties":{"$ref":"#/components/schemas/HexString"}},"HexString":{"type":"string","description":"A string containing a hexadecimal encoding of a number.","pattern":"^0x([0-9A-Fa-f]{2})+$"}}}}
```

## The ErrorMessage object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ErrorMessage":{"type":"object","properties":{"message":{"type":"string"}}}}}}
```

## The CardholderSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderSearch":{"title":"Cardholder search","type":"object","properties":{"results":{"type":"array","description":"An array of cardholder summaries.","items":{"$ref":"#/components/schemas/CardholderSummary"}},"next":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"The link to the next page.  Absent if you have retrieved them all."}},"description":"An array of cardholder summaries, and a `next` link for more."},"CardholderSummary":{"title":"Cardholder summary","type":"object","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"A link to a [cardholder detail](models#cardholderdetail) object for this cardholder.\nThis is Command Centre's identifier for this cardholder:  use it whenever you need to\nspecify a cardholder in REST operations.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  No API calls use cardholder IDs.\n\nDeprecated.  Use the href instead.\n","readOnly":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"shortName":{"maxLength":16,"type":"string","description":"If you supply a string that is too long when creating or updating\na cardholder, Command Centre will truncate it.\n"},"description":{"type":"string"},"authorised":{"type":"boolean","description":"This is called 'Cardholder Authorised' in the administrative clients.  If false, Command\nCentre will deny card access decisions for this cardholder.\n\n`authorised` is false by default.  If you want a new cardholder to open doors, be sure to\nset it to true in your POST.\n\nYou need the 'Edit cardholders' privilege to set this true.  In versions prior to 8.80\nyour operator also needed that privilege to set it false, but in 8.80 and later\n'De-authorise cardholder' is enough on its own.\n"}},"description":"The cardholder search at `/api/cardholders` returns an array of these.  It is a subset of what\nyou get from a cardholder's detail page at `/api/cardholders/{id}` (linked as the href in this\nobject), to be more suitable for large result sets.\n"}}}}
```

## The CardholderSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderSummary":{"title":"Cardholder summary","type":"object","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"A link to a [cardholder detail](models#cardholderdetail) object for this cardholder.\nThis is Command Centre's identifier for this cardholder:  use it whenever you need to\nspecify a cardholder in REST operations.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  No API calls use cardholder IDs.\n\nDeprecated.  Use the href instead.\n","readOnly":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"shortName":{"maxLength":16,"type":"string","description":"If you supply a string that is too long when creating or updating\na cardholder, Command Centre will truncate it.\n"},"description":{"type":"string"},"authorised":{"type":"boolean","description":"This is called 'Cardholder Authorised' in the administrative clients.  If false, Command\nCentre will deny card access decisions for this cardholder.\n\n`authorised` is false by default.  If you want a new cardholder to open doors, be sure to\nset it to true in your POST.\n\nYou need the 'Edit cardholders' privilege to set this true.  In versions prior to 8.80\nyour operator also needed that privilege to set it false, but in 8.80 and later\n'De-authorise cardholder' is enough on its own.\n"}},"description":"The cardholder search at `/api/cardholders` returns an array of these.  It is a subset of what\nyou get from a cardholder's detail page at `/api/cardholders/{id}` (linked as the href in this\nobject), to be more suitable for large result sets.\n"}}}}
```

## The CardholderCommonFields object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderCommonFields":{"title":"Cardholder common details","description":"The fields shared by the cardholder GET, POST, and PATCH.\n","type":"object","properties":{"disableCipherPad":{"type":"boolean","deprecated":true,"description":"True if this cardholder should not have the numbers on an alarms terminal scrambled\nwhen the terminal is configured as a cipher pad.  Usually the reason is a vision\nimpairment, making a randomised keypad impracticable.\n\nDeprecated from 9.50 in favour of the `disableCipherPad` element in the accessibilities\narray.  This field can still be set for backwards compatibility, but only set one of the\ntwo:  setting them to disagreeing values will earn you a 400.\n"},"division":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"The division containing this cardholder.  You must send this when creating a\ncardholder.\n"},"notes":{"type":"string","description":"Free-form text.\n\nThe 'Edit Cardholder Notes' privilege lets you change cardholder notes however you\nlike, but 'Add Cardholder Notes' only lets you add more to the end.  To do that, read\nthe existing `notes` field, append your text, and send it back in a PATCH.  If you try\nto change the existing text the server will respond with a 4xx.\n\nYou will need one of those two privileges to edit notes.  'Create Cardholders' and\n'Edit Cardholders' let you set most cardholder fields, but not notes.\n\nBecause of the potential size of the notes field, the server does not return it unless\nyou ask for it with `fields=notes`.\n"},"notifications":{"type":"object","description":"This block shows the cardholder's notification settings.  It deserves some explanation.\n\nThe `enabled` bool is correct at the time of your call.  If false, CC will not be\nsending your cardholder any notifications.\n\nThe `from` and `until` date-times show if and when `enabled` will change.  When the\n`from` date-time passes, `enabled` will flip, the `from` date-time will take the\n`until` value, and `until` will become null.  This continues until `from` is null.\n\nYou can set `from` with a null `until`, but not `until` with a null `from`.  They must\nboth be in the future or null, and `from` must be before `until`.\n\nIf you want to simply turn a person's notifications on or off without any changes\nscheduled for the future, set `enabled` true or false and both `from` and `until`\nnull.","properties":{"enabled":{"type":"boolean"},"from":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"oidcLoginEnabled":{"type":"boolean","description":"If true, and they have an `oidcUserId`, the operator can log in to the Command Centre\nclient using their Entra ID username.\n\nAdded in 9.40.\n"},"oidcUserId":{"type":"string","description":"This user's Entra ID username.  This should be the operator's Entra ID 'User Principal\nName' found in the overview of the user's details in Entra ID Admin Center.\n\nSend the empty string `\"\"` to clear it.\n\nAdded in 9.40.\n"},"operatorLoginEnabled":{"type":"boolean","description":"True if this operator can log in to the interactive Command Centre clients.  Note that\na cardholder also needs a privilege to use the Configuration Client.\n"},"operatorUsername":{"type":"string","description":"The name that the operator uses when logging in to the interactive clients.  Absent if blank.\n\nSend the empty string `\"\"` to clear it.\n"},"operatorPasswordExpired":{"type":"boolean","description":"If true, the interactive clients will request a new password the next time this person\nlogs in.\n"},"personalDataDefinitions":{"type":"array","description":"All the personal data definitions and values for this cardholder.  It is an array of\nobjects, each with one key/value pair.  The key is the name of the PDF preceded by\nan '@'; the value is an object containing the definition of the PDF (common for all\ncardholders) and the value for this cardholder.  The `value` block of an image PDF will\ncontain an href to the image.\n\nYour visibility of a cardholder's PDF value depends entirely on the PDF's access\nsettings in your operator groups, or if it has none of those, its default privilege.\nThe PDF's division is irrelevant.  So if you were expecting a PDF value here when none\narrived, ensure the cardholder has a value for that PDF (because the server does not\nsend nulls) then check the PDF's access settings in all of your operator groups, then\nthe default visibility on the PDF item itself.\n\nWhen you send this array in a POST or PATCH, Command Centre will take the\n`notifications` flag from here.  It can take `value` from here too, but if you also\nsend a field in the root of the cardholder with the name of the PDF preceded by an\n'@', that one wins.\n\nTo request this block using the `fields` parameter, use `personalDataFields` (note\n'fields' not 'definitions').  Doing so will not only give you the\n`personalDataDefinitions` block, but also the values at the root level (with their names\npreceded by '@'-signs).\n","items":{"$ref":"#/components/schemas/CardholderPDF"}},"windowsLoginEnabled":{"type":"boolean","description":"If true, and they have a Windows username, this user can log in using Windows\nintegrated authentication.\n"},"windowsUsername":{"type":"string","description":"This user's Windows username.  For an example of the format that will work in your\norganisation, look in the 'Windows logon' field of the 'Operator configuration' tab of\na cardholder's properties in the Configuration Client.\n\nSend the empty string `\"\"` to clear it.\n"}}},"CardholderPDF":{"title":"Cardholder PDF","description":"A personal data definition and its value for a cardholder.  Each definition is an object\ncontaining one property named after the PDF (plus a leading '@'), which in turn contains its\nvalue and notifications flag for the containing cardholder and an object containing some of\nthe PDF definition's basic fields.\n\nThis is returned as part of a [cardholder](models#cardholderdetail), and you can send it\nin a [POST](models#cardholderpost) or a\n[PATCH](models#cardholderpatch) to set the PDF's value and notification flag for\na cardholder.  The server will ignore the `definition` block if you send it back.  It uses the\nname of the block (minus its leading `@`) to find the PDF to change.\n\nWhile you can use this structure to change the value of a cardholder's PDF, it may be simpler\nto put a property in the root of the payload named after the PDF with a leading '@'.\n","type":"object","additionalProperties":{"$ref":"#/components/schemas/CardholderPDFContent"}},"CardholderPDFContent":{"title":"Cardholder PDF content","type":"object","properties":{"href":{"type":"string","description":"GET this link to receive this cardholder's value for this PDF.  If it is an image you will\nreceive the raw image data with an appropriate content-type.  A browser will render it\ncorrectly.\n\nIf the PDF is not an image the content type will be text/plain, encoded (like\neverything else in this API) as UTF-8.  But you should only use it for image PDFs\nbecause:\n\n* Values for scalar PDF types (everything except images) are also given to you in the\n  `value` field in this object, described below.\n\n* The format of date PDFs varies with the Command Centre version.  Old servers return\n  it in a format that depends on the server's locale.  This was a bug.  Newer servers\n  use ISO 8601.\n\n* If you learn this URL while a cardholder has the PDF, then the cardholder loses\n  it, then you GET the URL, results will vary depending on the server version.  The\n  correct result is a 404, and if the PDF is an image or the server is recent you\n  will see that.  But old servers may return a blank string or even a 500 for\n  non-image PDFs.\n\nThis field will be absent if the cardholder does not have a value for the PDF.\n\nIt is read-only:  do not send it in a PATCH or POST.\n","format":"uri-reference","readOnly":true},"definition":{"type":"object","properties":{"href":{"type":"string","description":"This is the href of the PDF's definition, common to all cardholders who hold a value\nfor this PDF.\n","format":"uri-reference"},"name":{"type":"string","description":"The PDF's name, without an '@' prefix.\n"},"id":{"type":"string","description":"Short alphanumeric identifier used elsewhere in the API to filter cardholder searches\nand add PDF values to alarm and event GETs.\n"},"type":{"type":"string","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]}},"description":"The definition object is read-only:  do not send it in a PATCH or POST.\n","readOnly":true},"value":{"description":"In a GET response for text, numeric, and date PDFs this will be a scalar containing the\nvalue, but for image PDFs it will be an object containing a copy of the `href` field\nabove.  For date PDFs the string will comply with RFC 3339, but may or may not contain a\ntime depending on the version of Command Centre.  Newer versions omit the `T` separator\nand everything after it.  If there, it will be midnight UTC.\n\nIn versions up to and including 8.60, if a cardholder did not have an image PDF captured\n(in other words they were a member of an access group that included an image PDF, but they\ndid not have a value for it) the API returned the string 'Not captured' in the `value`\nfield.  Versions 8.70 and later will not return the `value` field at all if there is no image.\n\nIn a POST or PATCH send text PDFs (including dates) as strings, numeric PDFs as numbers or\nstrings that parse to numbers, and image data Base64-encoded into a string.\n","oneOf":[{"type":"integer","title":"Numeric","description":"The scalar value of the numeric PDF."},{"type":"string","title":"Text or date","description":"The scalar value of the text or date PDF."},{"type":"object","title":"Image","description":"An object containing an href which, when requested from the server, returns the\nimage PDF.  The server does not transcode images:  it will arrive as the same\ncontent type as uploaded.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"Only present for image PDFs, this will be a copy of the href field in the parent\nobject.  When requested from the server it will return the image PDF as it was\nuploaded.\n"}}}]},"notifications":{"type":"boolean","description":"In a GET response, this will only appear for email and mobile PDF types.  In a POST or\nPATCH, it only makes sense for the same types.\n\nIf true, cardholder notifications will go to the telephone number or email address held by\nthis PDF.  Cardholders can have their notifications go to as many contacts as they wish.\n"}}}}}}
```

## The CardholderDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderDetail":{"title":"Cardholder detail","description":"[/api/cardholders/{id}](cardholders#get-api-cardholders-id-) returns one of these, and you\nsubmit [parts of one](models#cardholderpost) in a POST to create a cardholder.\n\nYou may find it contains a block called `updates`.  This is reserved for future\ndevelopment and its behaviour will change in later versions of Command Centre.\n","allOf":[{"$ref":"#/components/schemas/CardholderSummary"},{"$ref":"#/components/schemas/CardholderCommonFields"},{"type":"object","title":"Detail fields","description":"Fields unique to the cardholder detail.","properties":{"lastSuccessfulAccessTime":{"type":"string","description":"The date and time of the last successful card event or operator-initiated movement\n(using a tag board or [this\nAPI](cardholders#post-api-cardholders-id-update_location)).\n","format":"date-time","readOnly":true},"lastSuccessfulAccessZone":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"}},"description":"The last zone the cardholder entered.\n\nIf their last movement was to the 'outside' (through a door that has no access zone\nconfigured for that direction of travel) this field will be missing but\n`lastSuccessfulAccessTime` will be present.\n\nIf the cardholder is a visitor and their last\nmovement was to leave the site, this will be their visit's reception, not an access\nzone.  8.50 and later will present only the name of the reception and withhold the\nhref in that case.\n\n**Change is coming.**\n\nA future version of Command Centre will add the href field even if the item is a\nreception.  So you can tell the difference, it will add a field called\n`canonicalTypeName` which will have one of two values:  `accesszone` or `reception`.\n","readOnly":true},"serverDisplayName":{"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n","readOnly":true},"usercode":{"type":"string","description":"This field is write-only, so you will not see it in the results of a GET.  It appears\nhere because you can send it in the body of a POST or PATCH.\n\nSet it to the empty string `\"\"` to clear the cardholder's user code.\n\nIf it is not empty it must be a string of at least four digits.  It may need to be\nlonger, because the minimum length is set by your site configuration.\n\nYou will find that \"0000\" does not work.\n"},"operatorPassword":{"type":"string","description":"The password this user must supply when logging in to the interactive clients, if they\nare not using Windows integrated authentication.\n\nCommand Centre imposes password length and complexity restrictions.  If your password\ndoes not meet those requirements, the entire update will fail.  The body of the 4xx\nresponse will tell you why.\n\nLike the user code, this is write-only so you will not see it in the results of a GET.\n"},"cards":{"type":"array","description":"All the cards for this cardholder.  Note that even though Command Centre\ncalls these things 'cards', they include other types that do not require a physical\ncard, such as digital IDs and mobile credentials.\n","items":{"$ref":"#/components/schemas/CardholderCard"}},"accessGroups":{"type":"array","description":"All the cardholder's access group memberships.  This does not list memberships the\ncardholder inherits through other groups.\n\nThe server property 'Show all cardholder access group memberships' does not affect the\nAPI as it affects the configuration and operational clients, so this field only\nappears if the operator has permission to see access group memberships.  That is\ngranted by a privilege such as 'View cardholders'.\n","items":{"$ref":"#/components/schemas/CardholderAccessGroup"}},"operatorGroups":{"type":"array","description":"All the cardholder's operator group memberships.  Added in 8.50.\n","items":{"$ref":"#/components/schemas/CardholderOperatorGroup"}},"competencies":{"type":"array","description":"Every competency a cardholder possesses.  There is quite a lot there:  see the schema\ndefinition for detailed explanation.\n","items":{"$ref":"#/components/schemas/CardholderCompetency"}},"edit":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Reserved for internal use.  It is a link to [another\ncall](cardholders#get-api-cardholders-id-edit) that helps interactive\nadministrative clients.  Do not send it when creating or editing a cardholder.\n","readOnly":true},"updateLocation":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Link to send a [POST](cardholders#post-api-cardholders-id-update_location) to when\nyou want to update the location of this cardholder.  Added in 8.20.\n","readOnly":true},"relationships":{"type":"array","description":"This is a list of the roles that other cardholders perform for this cardholder.\n\nSince only one cardholder can perform a given role for another, there will be no more\nelements in this array than there are roles on the site.\n\nThe example shows that this cardholder has one supervisor.\n","items":{"$ref":"#/components/schemas/CardholderRelationship"}},"lockers":{"type":"array","description":"All the cardholder's locker assignments.\n","items":{"$ref":"#/components/schemas/CardholderLocker"}},"elevatorGroups":{"type":"array","description":"The cardholder's elevator group properties. They may have one per elevator group.\n\nAdded in 8.50.\n","items":{"$ref":"#/components/schemas/CardholderElevatorGroup"}},"updates":{"deprecated":true,"type":"object","properties":{},"description":"Cardholders include an `updates` block, as other items do, that allows monitoring one\ncardholder per TCP session in a long poll.  However the [Cardholder\nchanges](cardholder-change-tracking) methods are a far more efficient way of monitoring\nyour cardholders.\n"},"redactions":{"type":"array","description":"All the cardholder's scheduled redactions.\n\nBecause this is relatively expensive to compute, this field does not appear by\ndefault.  You must ask for it with `fields=redactions` or\n`fields=redactions.href,redactions.type,redactions.when`, for example.\n\nAdded in 8.80.\n","items":{"$ref":"#/components/schemas/CardholderRedaction"}},"accessibilities":{"description":"The cardholder's accessibility settings in an array of three elements.\n\nNew to 9.50.\n","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["disableCipherPad","useExtendedAccessTime","pinExemption"],"description":"\n* `disableCipherPad` means this cardholder will not have the numbers on an\n  alarms terminal scrambled when the terminal is configured as a cipher pad.\n  Usually the reason is a vision impairment making a randomised keypad\n  impracticable.\n\n* `useExtendedAccessTime` increases the time a door remains unlocked and the\n  amount of time that can pass before raising a 'door open too long' alarm.\n\n* `pinExemption` bypasses PIN entry.  Users with this accessibility enabled who\n  badge a card at a reader that normally requires PIN entry will not be prompted\n  to enter a PIN.\n"},"enabled":{"type":"boolean","description":"If false, the accessibility is disabled.  If true, it depends on `from` and\n`until`.\n"},"from":{"type":"string","format":"date-time","description":"If set and in the future, the accessibility will not be active until then.  If\nnot set or in the past, the accessibility will depend on `enabled`.\n"},"until":{"type":"string","format":"date-time","description":"If set and in the past, the accessibility will have been inactive since then.\nIf not set or in the future, the accessibility will depend on `enabled`.\n\nIf you send it, it must be later than both the `from` date, if sent, and the\ncurrent time.\n"}}}}},"patternProperties":{"^@.+":{"description":"An example Personal Data Field value.\n\nAll PDFs except images appear at the top level of a cardholder in a field named\nafter the PDF with a leading '@'.\n\nDate PDFs will contain a date-time with the time part set to midnight.\n\nImage PDFs appear as a block containing an\nhref. GETting that href will return the image data with an appropriate\ncontent-type header.\n\nPut your PDF values here when creating or modifying a cardholder.  Note that to\nhold a PDF value the cardholder must be a member of an access group that has that\nPDF attached to it.  In this example, being a member of the special projects\ngroup has granted our Mr. Boothroyd the student ID and photo PDFs.\n\nTo set an image PDF, Base64-encode the image and send it as a string.  There is\none in the [cardholder POST example](models#cardholderpost).\n\nDate PDFs are only accurate to a day, so version 8.75 and later will ignore the\ntime and time zone components if you send them.  8.70 and earlier will first\nperform a timezone correction then convert it to UTC before truncating the time,\nwhich might shift the date back a day if you specified a positive timezone\noffset.  To be sure that does not happen on a server older than 8.75, put\n`T00:00:00Z` on the end of your date.\n"}}}]},"CardholderSummary":{"title":"Cardholder summary","type":"object","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"A link to a [cardholder detail](models#cardholderdetail) object for this cardholder.\nThis is Command Centre's identifier for this cardholder:  use it whenever you need to\nspecify a cardholder in REST operations.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  No API calls use cardholder IDs.\n\nDeprecated.  Use the href instead.\n","readOnly":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"shortName":{"maxLength":16,"type":"string","description":"If you supply a string that is too long when creating or updating\na cardholder, Command Centre will truncate it.\n"},"description":{"type":"string"},"authorised":{"type":"boolean","description":"This is called 'Cardholder Authorised' in the administrative clients.  If false, Command\nCentre will deny card access decisions for this cardholder.\n\n`authorised` is false by default.  If you want a new cardholder to open doors, be sure to\nset it to true in your POST.\n\nYou need the 'Edit cardholders' privilege to set this true.  In versions prior to 8.80\nyour operator also needed that privilege to set it false, but in 8.80 and later\n'De-authorise cardholder' is enough on its own.\n"}},"description":"The cardholder search at `/api/cardholders` returns an array of these.  It is a subset of what\nyou get from a cardholder's detail page at `/api/cardholders/{id}` (linked as the href in this\nobject), to be more suitable for large result sets.\n"},"CardholderCommonFields":{"title":"Cardholder common details","description":"The fields shared by the cardholder GET, POST, and PATCH.\n","type":"object","properties":{"disableCipherPad":{"type":"boolean","deprecated":true,"description":"True if this cardholder should not have the numbers on an alarms terminal scrambled\nwhen the terminal is configured as a cipher pad.  Usually the reason is a vision\nimpairment, making a randomised keypad impracticable.\n\nDeprecated from 9.50 in favour of the `disableCipherPad` element in the accessibilities\narray.  This field can still be set for backwards compatibility, but only set one of the\ntwo:  setting them to disagreeing values will earn you a 400.\n"},"division":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"The division containing this cardholder.  You must send this when creating a\ncardholder.\n"},"notes":{"type":"string","description":"Free-form text.\n\nThe 'Edit Cardholder Notes' privilege lets you change cardholder notes however you\nlike, but 'Add Cardholder Notes' only lets you add more to the end.  To do that, read\nthe existing `notes` field, append your text, and send it back in a PATCH.  If you try\nto change the existing text the server will respond with a 4xx.\n\nYou will need one of those two privileges to edit notes.  'Create Cardholders' and\n'Edit Cardholders' let you set most cardholder fields, but not notes.\n\nBecause of the potential size of the notes field, the server does not return it unless\nyou ask for it with `fields=notes`.\n"},"notifications":{"type":"object","description":"This block shows the cardholder's notification settings.  It deserves some explanation.\n\nThe `enabled` bool is correct at the time of your call.  If false, CC will not be\nsending your cardholder any notifications.\n\nThe `from` and `until` date-times show if and when `enabled` will change.  When the\n`from` date-time passes, `enabled` will flip, the `from` date-time will take the\n`until` value, and `until` will become null.  This continues until `from` is null.\n\nYou can set `from` with a null `until`, but not `until` with a null `from`.  They must\nboth be in the future or null, and `from` must be before `until`.\n\nIf you want to simply turn a person's notifications on or off without any changes\nscheduled for the future, set `enabled` true or false and both `from` and `until`\nnull.","properties":{"enabled":{"type":"boolean"},"from":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"oidcLoginEnabled":{"type":"boolean","description":"If true, and they have an `oidcUserId`, the operator can log in to the Command Centre\nclient using their Entra ID username.\n\nAdded in 9.40.\n"},"oidcUserId":{"type":"string","description":"This user's Entra ID username.  This should be the operator's Entra ID 'User Principal\nName' found in the overview of the user's details in Entra ID Admin Center.\n\nSend the empty string `\"\"` to clear it.\n\nAdded in 9.40.\n"},"operatorLoginEnabled":{"type":"boolean","description":"True if this operator can log in to the interactive Command Centre clients.  Note that\na cardholder also needs a privilege to use the Configuration Client.\n"},"operatorUsername":{"type":"string","description":"The name that the operator uses when logging in to the interactive clients.  Absent if blank.\n\nSend the empty string `\"\"` to clear it.\n"},"operatorPasswordExpired":{"type":"boolean","description":"If true, the interactive clients will request a new password the next time this person\nlogs in.\n"},"personalDataDefinitions":{"type":"array","description":"All the personal data definitions and values for this cardholder.  It is an array of\nobjects, each with one key/value pair.  The key is the name of the PDF preceded by\nan '@'; the value is an object containing the definition of the PDF (common for all\ncardholders) and the value for this cardholder.  The `value` block of an image PDF will\ncontain an href to the image.\n\nYour visibility of a cardholder's PDF value depends entirely on the PDF's access\nsettings in your operator groups, or if it has none of those, its default privilege.\nThe PDF's division is irrelevant.  So if you were expecting a PDF value here when none\narrived, ensure the cardholder has a value for that PDF (because the server does not\nsend nulls) then check the PDF's access settings in all of your operator groups, then\nthe default visibility on the PDF item itself.\n\nWhen you send this array in a POST or PATCH, Command Centre will take the\n`notifications` flag from here.  It can take `value` from here too, but if you also\nsend a field in the root of the cardholder with the name of the PDF preceded by an\n'@', that one wins.\n\nTo request this block using the `fields` parameter, use `personalDataFields` (note\n'fields' not 'definitions').  Doing so will not only give you the\n`personalDataDefinitions` block, but also the values at the root level (with their names\npreceded by '@'-signs).\n","items":{"$ref":"#/components/schemas/CardholderPDF"}},"windowsLoginEnabled":{"type":"boolean","description":"If true, and they have a Windows username, this user can log in using Windows\nintegrated authentication.\n"},"windowsUsername":{"type":"string","description":"This user's Windows username.  For an example of the format that will work in your\norganisation, look in the 'Windows logon' field of the 'Operator configuration' tab of\na cardholder's properties in the Configuration Client.\n\nSend the empty string `\"\"` to clear it.\n"}}},"CardholderPDF":{"title":"Cardholder PDF","description":"A personal data definition and its value for a cardholder.  Each definition is an object\ncontaining one property named after the PDF (plus a leading '@'), which in turn contains its\nvalue and notifications flag for the containing cardholder and an object containing some of\nthe PDF definition's basic fields.\n\nThis is returned as part of a [cardholder](models#cardholderdetail), and you can send it\nin a [POST](models#cardholderpost) or a\n[PATCH](models#cardholderpatch) to set the PDF's value and notification flag for\na cardholder.  The server will ignore the `definition` block if you send it back.  It uses the\nname of the block (minus its leading `@`) to find the PDF to change.\n\nWhile you can use this structure to change the value of a cardholder's PDF, it may be simpler\nto put a property in the root of the payload named after the PDF with a leading '@'.\n","type":"object","additionalProperties":{"$ref":"#/components/schemas/CardholderPDFContent"}},"CardholderPDFContent":{"title":"Cardholder PDF content","type":"object","properties":{"href":{"type":"string","description":"GET this link to receive this cardholder's value for this PDF.  If it is an image you will\nreceive the raw image data with an appropriate content-type.  A browser will render it\ncorrectly.\n\nIf the PDF is not an image the content type will be text/plain, encoded (like\neverything else in this API) as UTF-8.  But you should only use it for image PDFs\nbecause:\n\n* Values for scalar PDF types (everything except images) are also given to you in the\n  `value` field in this object, described below.\n\n* The format of date PDFs varies with the Command Centre version.  Old servers return\n  it in a format that depends on the server's locale.  This was a bug.  Newer servers\n  use ISO 8601.\n\n* If you learn this URL while a cardholder has the PDF, then the cardholder loses\n  it, then you GET the URL, results will vary depending on the server version.  The\n  correct result is a 404, and if the PDF is an image or the server is recent you\n  will see that.  But old servers may return a blank string or even a 500 for\n  non-image PDFs.\n\nThis field will be absent if the cardholder does not have a value for the PDF.\n\nIt is read-only:  do not send it in a PATCH or POST.\n","format":"uri-reference","readOnly":true},"definition":{"type":"object","properties":{"href":{"type":"string","description":"This is the href of the PDF's definition, common to all cardholders who hold a value\nfor this PDF.\n","format":"uri-reference"},"name":{"type":"string","description":"The PDF's name, without an '@' prefix.\n"},"id":{"type":"string","description":"Short alphanumeric identifier used elsewhere in the API to filter cardholder searches\nand add PDF values to alarm and event GETs.\n"},"type":{"type":"string","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]}},"description":"The definition object is read-only:  do not send it in a PATCH or POST.\n","readOnly":true},"value":{"description":"In a GET response for text, numeric, and date PDFs this will be a scalar containing the\nvalue, but for image PDFs it will be an object containing a copy of the `href` field\nabove.  For date PDFs the string will comply with RFC 3339, but may or may not contain a\ntime depending on the version of Command Centre.  Newer versions omit the `T` separator\nand everything after it.  If there, it will be midnight UTC.\n\nIn versions up to and including 8.60, if a cardholder did not have an image PDF captured\n(in other words they were a member of an access group that included an image PDF, but they\ndid not have a value for it) the API returned the string 'Not captured' in the `value`\nfield.  Versions 8.70 and later will not return the `value` field at all if there is no image.\n\nIn a POST or PATCH send text PDFs (including dates) as strings, numeric PDFs as numbers or\nstrings that parse to numbers, and image data Base64-encoded into a string.\n","oneOf":[{"type":"integer","title":"Numeric","description":"The scalar value of the numeric PDF."},{"type":"string","title":"Text or date","description":"The scalar value of the text or date PDF."},{"type":"object","title":"Image","description":"An object containing an href which, when requested from the server, returns the\nimage PDF.  The server does not transcode images:  it will arrive as the same\ncontent type as uploaded.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"Only present for image PDFs, this will be a copy of the href field in the parent\nobject.  When requested from the server it will return the image PDF as it was\nuploaded.\n"}}}]},"notifications":{"type":"boolean","description":"In a GET response, this will only appear for email and mobile PDF types.  In a POST or\nPATCH, it only makes sense for the same types.\n\nIf true, cardholder notifications will go to the telephone number or email address held by\nthis PDF.  Cardholders can have their notifications go to as many contacts as they wish.\n"}}},"CardholderCard":{"title":"Cardholder card","type":"object","properties":{"href":{"type":"string","readOnly":true,"description":"DELETE this link to delete a card.\n\nDo not specify it when creating a card.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404 in the\ncurrent versions of Command Centre.\n","format":"uri-reference"},"number":{"type":"string","description":"For a physical access card, this is its card number.  It must be unique across all cards\nof the same card type.  If you leave it blank when creating a card of a type that has a\ndecimal number format, Command Centre will use the next available number.\n\nCard numbers for a mobile credential need not be unique.  They are strings, and are not\nused by Command Centre except for display.\n\nCard numbers for digital IDs are GUIDs.\n\nThis field is mandatory for card types with text or PIV number formats.  If the card type\nhas a text card number format with a regular expression and you supply a card number that\ndoes not match that regex, Command Centre will reject your update.\n\nPIV card numbers must be the same as the card's FASC-N.  PIV-I card numbers must not.\n\nThis field is also mandatory for PIV, PIV-I, tracking tag, GovPass, and Universal Credential\n(`profileCredential`) classes.\n\nOne rule is common across all card types:  you cannot change the number of an existing\ncard or credential.\n"},"cardSerialNumber":{"type":"string","description":"The serial number (CSN, MIFARE UID) of a physical access card as a hex string without a\nleading '0x'.  The number is encoded in the traditional way, with an even number of\nnumbers and the letters from 'A' through 'F', but the '0x' is missing when it comes out\nof the API and it must be missing when you send it back.\n\nThe example shows a seven-byte serial in the order you can expect in a\nGET and should use in a PATCH or POST.  Those on NXP MIFARE cards start with 04 and end\nwith 80 or 90.\n\nFour-byte serial numbers are in the same format, but shorter: `\"EBD62D25\"`, for example.\n\nThis may not be present on very old cards.\n\nThis field was read-only until 7.90.  It is read-write in 8.00 and later.\n"},"issueLevel":{"maximum":15,"minimum":0,"type":"integer","description":"The issue level of a physical access card.  If two cards have the same number\nbut different issue levels, only the one with this issue level will gain access.\n\nIf you leave it blank when creating a card, Command Centre will pick an appropriate value.\n\nIf you increase it when modifying a card, all cards with lower issue levels will stop working.\n\nThe only credential classes for which an issue level is relevant are `card`, PIV, and\nPIV-I.  Some other credential classes currently accept and ignore issue levels, but may\nreject them in a future version.\n"},"status":{"type":"object","properties":{"value":{"type":"string","description":"This card's state, taken from the card type's state set.  The default card\nstate set contains 'Active', 'Disabled (manually)', 'Lost', 'Stolen', and\n'Damaged', or translations of those into the server's language.  Your card state sets may\ndiffer, as they are customisable. [PIV cards](piv) have extra values.\n\nIn addition to the values in the card type's state set, it will be 'Not Yet Activated'\nif the card's activation date is in the future, 'Expired' if its deactivation date has\npassed, or 'Disabled (by inactivity)' if that is the site's policy and the card has\nnot been used at a door.\n\nBecause the value of the `value` field is set by site administrators, you\nshould not use it for programmatically determining whether a card is active.\nUse `type` instead.  Use `value` for display.\n\nWhen creating or updating a card, set `value` to one of the valid card states from the\ncard state set.  Command Centre is not fussy about case.  If you omit it when you\ncreate a card, Command Centre will use the default for the card state set (which is\n'active' for the factory state set).\n\nIf you omit both this and the PIV status when creating or updating a PIV card, or omit\nthis and set the PIV status to 'normal' or 'offline', the server will set this to\n'active'.  Any other PIV status will cause the card to become inactive, regardless of\nwhat you put here.  So you really only need to set this when you are changing the PIV\nstatus to 'normal' or 'offline' but you want to disable the card.  In that case, set\n`status.value` to 'disabled (manually)'.\n"},"type":{"type":"string","description":"This will be 'pending' if the activation date (`from`) is in the future,\n'expired' if its deactivation date (`until`) is in the past, or 'inactive'\nif it is disabled for one of the reasons given in the card state.\n\nNever send `type`:  Command Centre always infers it.\n","readOnly":true,"enum":["pending","active","expired","inactive"]}},"description":"Each card has two status codes:  `value`, and `type`, covered in separate sections below.\n\n`value` is human-readable.  It comes from the _Card State Set_ configured by the site, and\ncould be adjusted according to the card's activation dates.  The REST API and this\ndocument do not cover card state sets because in most cases, the default set is\nsufficient.  See the online help for the Command Centre client if you wish to create your\nown.\n\nThe second field, `type`, comes from a fixed enumeration, and so is better suited than\n`value` for integrations.  Command Centre derives it from the card's state and activation\ndates.\n"},"type":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"}},"description":"The name of the card type from the site configuration, and a link to the card type object.\n\nWhen creating a card, the href must be a card type that makes sense for the other values\nyou placed in this object.\n\nYou cannot change a card's type once it is created.\n"},"invitation":{"type":"object","properties":{"email":{"type":"string","description":"The email address to which Command Centre will send or did send an invitation for this\ncredential.\n"},"mobile":{"type":"string","description":"The telephone number to which Command Centre will send or did send an SMS containing a\nconfirmation code for this invitation.\n"},"singleFactorOnly":{"type":"boolean","description":"If you set this true Command Centre will not require a PIN or fingerprint from the\ncardholder when they enrol.  Be aware that without that second authentication factor,\nzones in modes that require a PIN and readers that always require a second factor will\nnot grant access to the cardholder.\n\n`singleFactorOnly` will only be in the result of a GET if it is true.  If it is false,\nthe field will be missing.\n","default":false},"status":{"type":"string","description":"\n- `sent` means Command Centre is waiting for the user to accept the invitation, either\n  in Gallagher Mobile Connect or another app that uses the Mobile Connect SDK.\n\n- `accepted` means that the credential is ready for use.\n\n- `notSent` means the credential is only a few seconds old or Command Centre is having\n  trouble contacting the cloud.\n\n- `expired` means that Command Centre did not receive a response in time.\n","readOnly":true,"enum":["notSent","sent","expired","accepted"]},"href":{"type":"string","description":"Mobile applications use this URL to accept this invitation.  See the Mobile Connect\nSDK documentation for how to do that in your own applications.\n\nOnly present if `status` is 'sent'.\n","format":"uri-reference","readOnly":true}},"description":"Command Centre will only return this object for a mobile credential, and you should send\nit only when creating one.  In the interests of security you cannot modify the invitation\nblock of an existing credential.  Someone's thumb might be on its way to accept it, after all.\nIf there was something wrong with it you should delete it and start afresh.\n\nWhether you should send `mobile` or `email` when creating a mobile credential depends on\nwhether you are using the Gallagher mobile apps or your own.\n\nIf you specify either `mobile` or `email` to early-version servers you must also supply the\nother so that Command Centre can send both an email invitation and a confirmation SMS.  It\nis an error to only specify one on those servers.\n\nLater versions of Command Centre made the SMS verification optional to better support\ninstallations that use the Gallagher apps but prefer not to depend on cellular connectivity.\nYou do not need to send a mobile number when creating such a credential.\n\nIf you do not give an email address Command Centre cannot send an invitation to the\ncardholder.  It will be up to another application to complete the creation of this\ncredential using the Mobile Connect SDK.\n\nYou should not send a mobile number when creating a credential for use by third-party apps\nthat use the Mobile Connect SDK.  SMS is not supported there.\n\nFor more detail on using the Mobile Connect SDK, including more complete coverage of how\nan email address and mobile number are used in the provisioning process, see its\ndocumentation at [gallaghersecurity.github.io](https://gallaghersecurity.github.io).\n"},"from":{"type":"string","description":"The start of the time period during which this card is active.  If this time is in the\nfuture, the card is not active.\n\nWhen it is not set, Command Centre acts as though it is set to a time in the distant past.\n\nWhen creating a card, leave this property out (or send `null`) to use the card type's\ndefault start time, if the card type has one.  Send an empty string `\"\"` to create the card\nwith no start time even when the card type has a default.  `from` and `until` are treated\nindependently, so leaving out `from` while sending `until` still applies the card type's\ndefault `from`.\n\nWhen modifying a card, send an empty string `\"\"` to reset it.\n\nAny value you send other than a blank string or null must be in RFC 3339 format,\nincluding a timezone.  It must be before midnight on the morning of January 1, 2100 in\nthe server's _local_ time (so servers with positive timezone offsets have maximums\nduring December 31 2099), and it must be less than or equal to the `until` time.  A\nfuture version of Command Centre will clamp too-high values to December 31 2099 and\nreturn a 2xx (success) instead of 400 in that case.\n\nThe server rejects a timestamp that is not in an acceptable format with a 400, whether the\ncard is being created or modified.\n","format":"date-time"},"until":{"type":"string","description":"The end of the time period during which this card is active.  If this time is in the past,\nthe card is not active.\n\nWhen it is not set, Command Centre acts as though it is set to a time in the distant future.\n\nWhen creating a card, leave this property out (or send `null`) to use the card type's\ndefault expiry, if the card type has one: either its fixed end time, or its duration\ncounted from the time the card is created.  Send an empty string `\"\"` to create the card\nwith no end time even when the card type has a default.  `from` and `until` are treated\nindependently, so leaving out `until` while sending `from` still applies the card type's\ndefault `until`.\n\nWhen modifying a card, send an empty string `\"\"` to reset it.\n\nAny value you send other than a blank string or null must be in RFC 3339 format,\nincluding a timezone.  It must be before midnight on the morning of January 1, 2100 in\nthe server's _local_ time (so servers with positive timezone offsets have maximums\nduring December 31 2099), and it must be greater than or equal to the `from` time.  A\nfuture version of Command Centre will clamp too-high values to December 31 2099 and\nreturn a 2xx (success) instead of 400 in that case.\n\nThe server rejects a timestamp that is not in an acceptable format with a 400, whether the\ncard is being created or modified.\n","format":"date-time"},"credentialClass":{"type":"string","description":"This indicates the type of the card.  It comes from an enumeration, and is a reliable way\nof determining the credential's type.\n\nAdded in 8.00.\n\nThe experimental `applePass` was added in 9.10.  Its name may change in future versions.\n\nThe `govPass` credential class will change its name in 9.30.\n","readOnly":true,"enum":["card","digitalId","govPass","mobile","piv","pivi","profileCredential","trackingTag","transact"]},"trace":{"type":"boolean","description":"If set, using this credential will generate an event.\n\nThis field is not in the default set so you will not see it unless you ask for it using\nthe `fields` query parameter.\n\nAdded in 8.30.\n"},"lastPrintedOrEncodedTime":{"type":"string","description":"The date and time this card was last printed or encoded.  It will not come out by\ndefault - you need to ask for it with `fields=cards.lastPrintedOrEncodedTime`.\n\nAdded in 8.40.\n","format":"date-time","readOnly":true},"lastPrintedOrEncodedIssueLevel":{"maximum":15,"minimum":1,"type":"integer","description":"The issue level of this card when it was last printed or encoded, provided it was\nnon-zero.  It will not come out by default - you need to ask for it with\n`fields=cards.lastPrintedOrEncodedIssueLevel`.\n\nAdded in 8.40.\n","readOnly":true},"lastUsedTime":{"description":"When a Gallagher controller last observed the credential in use.\n","type":"string","format":"date-time","readOnly":true},"pin":{"type":"string","description":"This is a write-only field.\nYou can use it in POSTs and PATCHes but the server will not send it to you.\n\nBeing numeric, you might be tempted to send PINs to the server without surrounding\nquotes.  However if you do that, leading zeros will be lost and the resulting behaviour\nis undefined.\n\n8.90 servers will reject your request if the card's `credentialClass` is not `card`,\n`piv`, `pivi`, or `govPass`.  More recent servers will issue a warning in that case, and\nwill not set the PIN, but will allow the rest of the update.\n\nPINs were added to the API in 8.90.\n"},"visitorContractor":{"type":"boolean","description":"This is a credential property only for GovPass, indicating that the enrolled credential is\nfor a visitor / contractor.\n\nIt is a write-once field new to 9.00.\n"},"ownedBySite":{"type":"boolean","description":"This is a credential property only for GovPass, indicating if the site is the owner of the\ncard.\n\nIt is a read-only field new to 9.00.\n","readOnly":true},"credentialId":{"type":"string","description":"Reserved for use by Gallagher applications."},"bleFacilityId":{"type":"string","description":"Reserved for use by Gallagher applications."},"encodingData":{"type":"object","readOnly":true,"properties":{"mifareClassic":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"mifareDesfire":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}},"description":"This block contains links to the calls that return the data you will need to encode\nMIFARE DESFire and Classic cards.  For more on that see the 'Card Encoding' tag.\n\nRead-only:  the server will ignore it if you send it.\n\nAdded in 9.50.\n\nNot returned by default:  ask for it by adding `cards.encodingData` to your `fields`\nquery parameter.\n"},"deviceType":{"type":"string","enum":["applePhone","appleWatch","androidPhone","androidWatch"],"description":"Required when creating a wallet credential.  Either `applePhone` or `appleWatch` when\ncreating an Apple credential, and either `androidPhone` or `androidWatch` for Google.\n\nWallet credentials are part of the Universal Credentials feature added in 9.60.\n"}},"description":"A _card_ is an access credential, including physical cards and mobile (Bluetooth and NFC)\ncredentials and digital IDs.  The server returns it as part of a [cardholder's\ndetails](models#cardholderdetail), and you supply it when creating or modifying a card\nor credential on a cardholder.\n\nEvery card has a type, a status, and a validity period.  Its type determines other fields of\nrelevance, described below.\n\nPIV cards are complex enough to warrant a [tag of their own](piv).\n"},"CardholderAccessGroup":{"title":"Cardholder access group membership","type":"object","properties":{"href":{"type":"string","description":"This is the href of the cardholder's membership to an access group, not an access group\nitem.\n\nDELETE it to remove this group membership, and use it in the body of a PATCH to a\ncardholder to identify memberships you want to modify.\n\nNote that changing an access group membership with a PATCH will change this href, so do\nnot cache it.\n\nDELETE is the only verb you can use on this URL.  GET returns a 404.\n","format":"uri-reference"},"accessGroup":{"type":"object","description":"An object containing the group's href (which is also a link to its detail page) and,\nwhen sent by the server, the group's name.  You should not send this object when\nmodifying a group membership because you cannot change a group membership's group; you\ncan only change its dates.  But you must send it when adding a new group membership, of\ncourse, because it identifies the cardholder's new group.  Just send the group's href:\ndon't bother with the name.\n\n8.70 and later will not return the link if your operator does not have the privilege to\nview the access group (given by 'View access groups', for example).\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"status":{"type":"object","properties":{"value":{"type":"string","description":"The state of this cardholder's access group membership, in the site's language.  In an\nEnglish locale the value is the same as the type, but capitalised.\n","readOnly":true},"type":{"type":"string","description":"The state of this cardholder's access group membership.\n\nThis will be 'pending' if the activation date is set and in the future,\n'expired' if its deactivation date is set and in the past, or 'active'.\n","readOnly":true,"enum":["pending","expired","active"]}},"description":"The two fields in this block are read-only because they are determined by the `from` and\n`until` dates.\n","readOnly":true},"from":{"type":"string","description":"The start of the time period during which this group membership is active.  If this time\nis in the future, the membership will be inactive.  If null or in the past and `until`\nis null or in the future, the membership will be active.\n\nWhen sending this to a server of version 7.90.883 or earlier, use UTC with a trailing 'Z'.\nMore recent versions understand timezone offsets.\n","format":"date-time"},"until":{"type":"string","description":"The end of the time period during which this group membership is active.  If this time\nis in the past, the membership will be inactive.  If null or in the future and `from` is\nnull or in the past, the membership will be active.\n\nWhen sending this to a server of version 7.90.883 or earlier, use UTC with a trailing 'Z'.\nMore recent versions understand timezone offsets.\n","format":"date-time"}},"description":"An _access group_ is an object in Command Centre.  This section is about a connection between an access group and\na cardholder, called a _membership_.  A cardholder can be a member of many groups, and groups\ncan have any number of members.\n\nLess obvious is that a cardholder can have many memberships to the same group.  This is useful\nbecause a membership has a validity period, expressed with `from` and `until` date-times.\nOutside those moments Command Centre does not regard the cardholder as being a member of the\ngroup.  If there exists one membership with `from` in the past or unset and `until` in the\nfuture or unset, the cardholder is a member.\n\nPresence in an access group affects physical access rights and possession of PDFs, among other\nthings.\n\nThe membership object will come from the server in a cardholder's details if you ask for it, and you send it to\nthe server when modifying a cardholder's group memberships.  All uses are described below.\n"},"CardholderOperatorGroup":{"title":"Cardholder operator group membership","description":"An _operator group_ is an object in Command Centre.  The connection between an operator group\nand a cardholder is a _membership_.  A cardholder can be a member of many different operator\ngroups, and operator groups usually have more than one member, but a cardholder can only have\none membership to a given operator group at a time.  This is because an operator group\nmembership, unlike an access group membership, does not have start and end dates.\n\nPresence in an operator group affects software access.  Your REST operator, for example, must\nbe in an operator group that grants privileges otherwise it will receive nothing but 404s.\n\nAdded to the API in 8.50.\n","type":"object","properties":{"href":{"type":"string","description":"DELETE this URL or use it in the `operatorGroups` block of a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-) to remove this operator group\nmembership.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n","format":"uri-reference"},"operatorGroup":{"type":"object","description":"An object containing a link to this operator group's detail page and its name.\n\nThe link will be absent from the results of a GET if your operator does not have the\nprivilege to view the operator group ('View operators' or 'Edit operators', for\nexample).\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"CardholderCompetency":{"title":"Cardholder competency","description":"A _competency_ is an object in Command Centre with some basic fields like a name and a notice\nperiod.  Its purpose is to allow a site to refuse access to cardholders who do not meet a\nspecial requirement.\n\nThis section describes the link between a cardholder and a competency.  The status of that link\ndetermines whether they \"hold\" the competency for the purposes of access control decisions at\nthe door.  When we talk about updating, adding, or deleting a competency in the cardholder\nAPI, we do not mean the competency object itself, but rather the link a cardholder has to the\ncompetency.\n\nThe link between cardholder and competency is a block in the cardholder detail.  You can\nalso request the server to add it to the results of a cardholder search by putting\n`competencies` in the `fields` parameter.\n\nWhen updating a cardholder's holding of a competency, the fields you send are slightly\ndifferent from what you receive from a cardholder GET:  you do not send read-only blocks\nsuch as `status` and `competency`, and there is a write-only field `enabled` that you can\nsupply to change the status.\n\nYou cannot use a PATCH to move the status, times, comment, and credit to a different\ncompetency.  If you need to do that, delete the cardholder's existing competency and give\nthem a new one.  You can do that in one PATCH.\n\nA cardholder can have only one link to a given competency.  Attempting to give a cardholder\na competency a second time will either fail or raise a stateful alarm and succeed, depending\non your version of Command Centre.\n","type":"object","properties":{"href":{"type":"string","description":"This is the URL of the cardholder's connection to a competency, not the URL of the\ncompetency itself.  Use it as the target of a DELETE to remove a cardholder's\ncompetency, or in the body of a cardholder PATCH to modify it.\n\nDELETE is the only verb you can use on this URL.  GET will return a 404.\n","format":"uri-reference","readOnly":true},"competency":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}},"description":"This contains the competency's name and its href.\n\nAs ever, do not bother putting `name` in the body of a POST or PATCH.  The server will\nignore it.\n"},"status":{"type":"object","properties":{"value":{"type":"string"},"type":{"type":"string"}},"description":"This object contains two strings.  Both are read-only, so do not specify them when\nassigning or updating a cardholder's competency.  `value` is taken from the site's\nlanguage pack, suitable for display. `type` comes from a fixed enumeration.  It will be\n`expiryDue` or `active` when the cardholder carries this competency; anything else means\nno.  A fuller explanation follows.\n\nA competency can be disabled, expired, both, or neither.  Whether it is _enabled_ is a\nflag on the cardholder's holding of the competency.  Whether it is _expired_ is derived from an expiry\ntimestamp (accurate to the second):  if it is in the past, Command Centre considers the\ncompetency expired.\n\nA competency can also have an `enablement` date.  If that date (timestamp) passes while the\ncompetency is disabled, Command Centre will enable the competency.  It will leave the date on\nthe item for future reference, though it will not affect the competency again.\n\nIf the competency is disabled, the status `type` will be `inactive` when there is no\nenable date or it is in the past, and `pending` when the enable date is in the future\n(i.e., there is an automatic re-enablement coming).\n\nIf the competency is not disabled, the `expiry` time is important.  If it is in the past,\n`type` will be `expired`.\n\nAll of those cases are negative.  Two remain, when our cardholder is blessed with an\nenabled and active competency.  `type` will be `expiryDue` if the `expires` time is in the\nfuture but within the competency's advance notice period, or `active` if the `expires`\ntime is beyond the advance notice period or not set at all.\n\nYou can see and set the enabled flag, the enable date, and the expiry date via this\nAPI.\n\nWhen creating a cardholder or updating a competency on an existing cardholder, you should\nset the `enabled` field one way or the other, and the `enablement` and `expiry` dates if\nyou wish.  They will determine the contents of this status block.\n\nHere it is in table form.  The first two rows are the positive cases, when Command Centre\nwould grant access to a competency-enforced zone.\n\n| Enabled flag | Enablement date | Expiry date | `status.type`\n| ------------ | -------------- | --------| ----- |\n| true | - | Far future | active |\n| true | - | Near future | expiryDue |\n| true | - | Past | expired |\n| false | Future | - | pending |\n| false | Past | - | inactive |\n| false | Unset | - | inactive |\n","readOnly":true},"disabled":{"type":"boolean","readOnly":true,"deprecated":true,"description":"Do not use this field.  Instead, take the state of a cardholder's competency from\n`status.type`.  This field is misleading on its own:  even when it is true, the\ncompetency might still be inactive.\n"},"enabled":{"type":"boolean","writeOnly":true,"description":"This is a write-only field.  You will not receive it from the GET.  It changes the\ncompetency between enabled (status type `expired`, `expiryDue`, or `active`) and\ndisabled (status type `inactive` or `pending`).  Set it to false in a PATCH if you want\nto disable the competency now, particularly if you are setting a future enablement date.\n"},"expiryWarning":{"type":"string","description":"The time at which the cardholder will (or did) receive a warning about the\ncompetency expiring.  If this time is set and in the past but the competency has\nnot yet expired and is still enabled, the status type will be `expiryDue`.\n","format":"date-time","readOnly":true},"expiry":{"type":"string","description":"The time at which the competency will expire.  If this time is set, in the past, and the\ncompetency is enabled, status type will be `expired`.\n","format":"date-time"},"enablement":{"type":"string","description":"The time at which the competency will be re-enabled.  If set and in the future, and the\ncompetency is disabled, the status type will be `pending`.\n\nYou can set this on an enabled competency but it has no effect there, so with this field\nyou would generally also set `enabled: false`.\n","format":"date-time"},"comment":{"type":"string","description":"The comment appears in the management clients when viewing the cardholder.\n"},"limitedCredit":{"type":"boolean","description":"If false, Command Centre's 'Pre-pay Car Parking' feature (available under its own licence)\nwill not reduce the current credit.\n\nThis field will be in the results if its value is true.\n"},"credit":{"type":"integer","description":"The balance, or amount of credit left on this competency for use by Pre-pay Car Parking.\nIt can be negative.\n\nThis field will be in the results if its value is not zero.\n"}}},"CardholderRelationship":{"title":"Cardholder relationship","description":"A _role_ is an object in Command Centre.  Roles are usually named using nouns such as\n'supervisor', 'manager', or 'team leader'.\n\nThe operator clients and the REST API allow you to create a link between two\ncardholders, called a relationship, using a role.  The link is directional:  we\nrefer to the cardholder who 'has' the role as the child, and the cardholder who\nperforms or 'is' the role as the parent.\n\nA parent can perform a role for any number of child cardholders, but a child can only have one\nrelationship (parent) for each role.  Command Centre will reject your submission if you try to\ncreate a relationship when one already exists for the same child and role.\n\nFor example, a role on your system might be 'supervisor'.  A cardholder can be a supervisor\nfor any number of others, but will only have one supervisor.\n\nLoops are possible:  two cardholders can supervise each other.\n\nThe REST API manages relationships through the child cardholder.  You can create them at the\nsame time as creating the child in a POST, or add them later in a PATCH.\n\nThere is currently no way to list all a cardholder's children in one request (everyone a\nparticular cardholder is supervising, for example).  You would achieve that by iterating\nthrough all cardholders, after re-reading the efficiency tips, and checking their\nrelationships - quite easily done in JSONPath.\n\nThis section describes the object you receive in a cardholder's detail page and you will send\nin a POST or PATCH.  The child cardholder does not appear in it because he or she is\nidentified by the URL of the request.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the href of the link between two cardholders.  DELETE it, or put it in\n`relationships.remove.href` of a PATCH directed at the child cardholder, to sever the\nrelationship.  Specify it in `relationships.update.href` of a PATCH to the child\ncardholder to update the relationship.\n\nDo not specify it when creating a new relationship.  The server generates it for you.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"role":{"type":"object","description":"This is the role that the parent identified in the `cardholder` block performs for the\ncardholder identified by the request URL.\n\nOnce set, this cannot be changed.  Command Centre will ignore it if you send it\nin an update PATCH.  If you need to swap a parent from one role to another, send\nan add and a delete in the same PATCH.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"cardholder":{"type":"object","description":"The href and name of the cardholder that performs this role.\n\nThe three name fields are read-only:  Command Centre sends them to you in the body of a\nGET but will ignore them if you send them in the body of a POST or PATCH.\n\nThis block and the href in it are unnecessary when deleting a relationship.  The href is\nrequired when creating one, and optional when updating, but strongly advised since the\ncardholder is the only thing about a relationship you can change.\n\n`firstName` and `lastName` appeared in 8.20.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for the parent cardholder."},"firstName":{"type":"string","readOnly":true},"lastName":{"type":"string","readOnly":true}}}}},"CardholderLocker":{"title":"Cardholder locker","description":"These appear in an array in a cardholder detail, showing the cardholder's allocated lockers.\nEach allocation has `from` and `until` dates, much like cards and access group memberships,\noutside of which the allocation is inactive.\n\nA locker can have allocations to more than one cardholder, with separate or overlapping\nperiods.  Unlike access groups, however, one cardholder cannot have more than one allocation\nto the same locker.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this to end a cardholder's use of a locker, or use it to identify the\nallocation you wish to modify in a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-).\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"locker":{"description":"The href in this object is a link to the allocated locker, and is the identifier to use\nwhen allocating the same locker to another cardholder.\n\nThe object also contains the name and short name of the locker, and the name and\nidentifying href of its bank.\n","type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for a locker."},"shortName":{"type":"string","readOnly":true},"lockerBank":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"from":{"description":"The start of the time period during which the cardholder has access to this locker.\n\nSend an empty string `\"\"` to reset it.\n","type":"string","format":"date-time"},"until":{"description":"The end of the time period during which the cardholder has access to this locker.\n\nSend an empty string `\"\"` to reset it, making the allocation permanent.\n","type":"string","format":"date-time"}}},"CardholderElevatorGroup":{"title":"Cardholder elevator group","description":"These appear in an array in a cardholder detail, showing the cardholder's elevator group\nproperties, and can go into the body of a POST or PATCH to set a cardholder's elevator group\nproperties.\n\nA cardholder can have one default floor per elevator group. The elevator system will\nprepare a car to carry that cardholder to the access zone shown here when the cardholder\nbadges a card at an appropriately configured kiosk.\n\nElevator system features can be activated by enabling the feature for an elevator group.\nFor example, 'VIP features' gives exclusive access to an elevator car to the passenger.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"The href of this cardholder's elevator group entry.  DELETE this to remove it from the\ncardholder.\n"},"elevatorGroup":{"type":"object","description":"The href and name of the elevator group for which this cardholder has a default\nfloor or passenger type.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"accessZone":{"type":"object","description":"The href and name of the access zone (floor) to which this cardholder is most\nlikely to want to travel after entering the group's main elevator lobby. This \nproperty will be missing if the cardholder does not have a default floor for this elevator group.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"enableCaptureFeatures":{"type":"boolean","description":"Cardholders can select and recall specific elevators to specific floors using\na kiosk. Once captured, the elevator car can be placed on independent service to\ngive users control of the car to clean the interior or perform maintenance.\n"},"enableCodeBlueFeatures":{"type":"boolean","description":"A special elevator mode which is commonly found in hospitals. It allows an elevator\nto be summoned to any floor for use in an emergency situation.\n"},"enableExpressFeatures":{"type":"boolean","description":"Allows the cardholder to program selected elevators to cycle continuously between two\nfloors for a pre-determined duration. For example, this feature can help hotels transport\nfood efficiently from their kitchen to a ballroom on another floor. You can also prevent\nother guests from boarding to provide your banquet guests with VIP treatment.\n"},"enableServiceFeatures":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop\nto their destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableService2Features":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop\nto their destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableService3Features":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop to\ntheir destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableVipFeatures":{"type":"boolean","description":"VIP operation allows cardholders to swipe a card or enter a PIN to isolate the elevator\nand provide uninterrupted access to their designated floor.\n"}}},"CardholderRedaction":{"title":"Cardholder redaction","description":"These appear in an array in a cardholder object.  Each describes a redaction scheduled for the\ncardholder.\n\nA cardholder can have multiple event redactions pending, because they can operate on events\nfrom different periods, but since a cardholder redaction removes the cardholder item there\ncan be only one.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this URL to cancel this redaction.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"type":{"type":"string","enum":["normalEvents","cardholder"],"description":"Whether this redaction is for cardholder events or cardholder information.\n"},"when":{"description":"When the redaction is meant to happen.  This should be in the future.  If it is in the past,\nthe service returns 400-Bad Request Invalid Start Time.\n\nOptional.  If it is absent, it means to do it asap.\n","type":"string","format":"date-time"},"before":{"description":"For event redactions, do not redact any events after this time.  No effect on cardholder\ninformation redactions.\n\nOptional.\n","type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","inProgress","cancelled","done","failed"],"description":"The status of this redaction.\n"},"redactionOperator":{"description":"A block containing the href and current name of the operator who scheduled the redaction.\n","type":"object"}}}}}}
```

## The CardholderPDF object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderPDF":{"title":"Cardholder PDF","description":"A personal data definition and its value for a cardholder.  Each definition is an object\ncontaining one property named after the PDF (plus a leading '@'), which in turn contains its\nvalue and notifications flag for the containing cardholder and an object containing some of\nthe PDF definition's basic fields.\n\nThis is returned as part of a [cardholder](models#cardholderdetail), and you can send it\nin a [POST](models#cardholderpost) or a\n[PATCH](models#cardholderpatch) to set the PDF's value and notification flag for\na cardholder.  The server will ignore the `definition` block if you send it back.  It uses the\nname of the block (minus its leading `@`) to find the PDF to change.\n\nWhile you can use this structure to change the value of a cardholder's PDF, it may be simpler\nto put a property in the root of the payload named after the PDF with a leading '@'.\n","type":"object","additionalProperties":{"$ref":"#/components/schemas/CardholderPDFContent"}},"CardholderPDFContent":{"title":"Cardholder PDF content","type":"object","properties":{"href":{"type":"string","description":"GET this link to receive this cardholder's value for this PDF.  If it is an image you will\nreceive the raw image data with an appropriate content-type.  A browser will render it\ncorrectly.\n\nIf the PDF is not an image the content type will be text/plain, encoded (like\neverything else in this API) as UTF-8.  But you should only use it for image PDFs\nbecause:\n\n* Values for scalar PDF types (everything except images) are also given to you in the\n  `value` field in this object, described below.\n\n* The format of date PDFs varies with the Command Centre version.  Old servers return\n  it in a format that depends on the server's locale.  This was a bug.  Newer servers\n  use ISO 8601.\n\n* If you learn this URL while a cardholder has the PDF, then the cardholder loses\n  it, then you GET the URL, results will vary depending on the server version.  The\n  correct result is a 404, and if the PDF is an image or the server is recent you\n  will see that.  But old servers may return a blank string or even a 500 for\n  non-image PDFs.\n\nThis field will be absent if the cardholder does not have a value for the PDF.\n\nIt is read-only:  do not send it in a PATCH or POST.\n","format":"uri-reference","readOnly":true},"definition":{"type":"object","properties":{"href":{"type":"string","description":"This is the href of the PDF's definition, common to all cardholders who hold a value\nfor this PDF.\n","format":"uri-reference"},"name":{"type":"string","description":"The PDF's name, without an '@' prefix.\n"},"id":{"type":"string","description":"Short alphanumeric identifier used elsewhere in the API to filter cardholder searches\nand add PDF values to alarm and event GETs.\n"},"type":{"type":"string","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]}},"description":"The definition object is read-only:  do not send it in a PATCH or POST.\n","readOnly":true},"value":{"description":"In a GET response for text, numeric, and date PDFs this will be a scalar containing the\nvalue, but for image PDFs it will be an object containing a copy of the `href` field\nabove.  For date PDFs the string will comply with RFC 3339, but may or may not contain a\ntime depending on the version of Command Centre.  Newer versions omit the `T` separator\nand everything after it.  If there, it will be midnight UTC.\n\nIn versions up to and including 8.60, if a cardholder did not have an image PDF captured\n(in other words they were a member of an access group that included an image PDF, but they\ndid not have a value for it) the API returned the string 'Not captured' in the `value`\nfield.  Versions 8.70 and later will not return the `value` field at all if there is no image.\n\nIn a POST or PATCH send text PDFs (including dates) as strings, numeric PDFs as numbers or\nstrings that parse to numbers, and image data Base64-encoded into a string.\n","oneOf":[{"type":"integer","title":"Numeric","description":"The scalar value of the numeric PDF."},{"type":"string","title":"Text or date","description":"The scalar value of the text or date PDF."},{"type":"object","title":"Image","description":"An object containing an href which, when requested from the server, returns the\nimage PDF.  The server does not transcode images:  it will arrive as the same\ncontent type as uploaded.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"Only present for image PDFs, this will be a copy of the href field in the parent\nobject.  When requested from the server it will return the image PDF as it was\nuploaded.\n"}}}]},"notifications":{"type":"boolean","description":"In a GET response, this will only appear for email and mobile PDF types.  In a POST or\nPATCH, it only makes sense for the same types.\n\nIf true, cardholder notifications will go to the telephone number or email address held by\nthis PDF.  Cardholders can have their notifications go to as many contacts as they wish.\n"}}}}}}
```

## The CardholderPDFContent object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderPDFContent":{"title":"Cardholder PDF content","type":"object","properties":{"href":{"type":"string","description":"GET this link to receive this cardholder's value for this PDF.  If it is an image you will\nreceive the raw image data with an appropriate content-type.  A browser will render it\ncorrectly.\n\nIf the PDF is not an image the content type will be text/plain, encoded (like\neverything else in this API) as UTF-8.  But you should only use it for image PDFs\nbecause:\n\n* Values for scalar PDF types (everything except images) are also given to you in the\n  `value` field in this object, described below.\n\n* The format of date PDFs varies with the Command Centre version.  Old servers return\n  it in a format that depends on the server's locale.  This was a bug.  Newer servers\n  use ISO 8601.\n\n* If you learn this URL while a cardholder has the PDF, then the cardholder loses\n  it, then you GET the URL, results will vary depending on the server version.  The\n  correct result is a 404, and if the PDF is an image or the server is recent you\n  will see that.  But old servers may return a blank string or even a 500 for\n  non-image PDFs.\n\nThis field will be absent if the cardholder does not have a value for the PDF.\n\nIt is read-only:  do not send it in a PATCH or POST.\n","format":"uri-reference","readOnly":true},"definition":{"type":"object","properties":{"href":{"type":"string","description":"This is the href of the PDF's definition, common to all cardholders who hold a value\nfor this PDF.\n","format":"uri-reference"},"name":{"type":"string","description":"The PDF's name, without an '@' prefix.\n"},"id":{"type":"string","description":"Short alphanumeric identifier used elsewhere in the API to filter cardholder searches\nand add PDF values to alarm and event GETs.\n"},"type":{"type":"string","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]}},"description":"The definition object is read-only:  do not send it in a PATCH or POST.\n","readOnly":true},"value":{"description":"In a GET response for text, numeric, and date PDFs this will be a scalar containing the\nvalue, but for image PDFs it will be an object containing a copy of the `href` field\nabove.  For date PDFs the string will comply with RFC 3339, but may or may not contain a\ntime depending on the version of Command Centre.  Newer versions omit the `T` separator\nand everything after it.  If there, it will be midnight UTC.\n\nIn versions up to and including 8.60, if a cardholder did not have an image PDF captured\n(in other words they were a member of an access group that included an image PDF, but they\ndid not have a value for it) the API returned the string 'Not captured' in the `value`\nfield.  Versions 8.70 and later will not return the `value` field at all if there is no image.\n\nIn a POST or PATCH send text PDFs (including dates) as strings, numeric PDFs as numbers or\nstrings that parse to numbers, and image data Base64-encoded into a string.\n","oneOf":[{"type":"integer","title":"Numeric","description":"The scalar value of the numeric PDF."},{"type":"string","title":"Text or date","description":"The scalar value of the text or date PDF."},{"type":"object","title":"Image","description":"An object containing an href which, when requested from the server, returns the\nimage PDF.  The server does not transcode images:  it will arrive as the same\ncontent type as uploaded.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"Only present for image PDFs, this will be a copy of the href field in the parent\nobject.  When requested from the server it will return the image PDF as it was\nuploaded.\n"}}}]},"notifications":{"type":"boolean","description":"In a GET response, this will only appear for email and mobile PDF types.  In a POST or\nPATCH, it only makes sense for the same types.\n\nIf true, cardholder notifications will go to the telephone number or email address held by\nthis PDF.  Cardholders can have their notifications go to as many contacts as they wish.\n"}}}}}}
```

## The CardholderCard object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderCard":{"title":"Cardholder card","type":"object","properties":{"href":{"type":"string","readOnly":true,"description":"DELETE this link to delete a card.\n\nDo not specify it when creating a card.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404 in the\ncurrent versions of Command Centre.\n","format":"uri-reference"},"number":{"type":"string","description":"For a physical access card, this is its card number.  It must be unique across all cards\nof the same card type.  If you leave it blank when creating a card of a type that has a\ndecimal number format, Command Centre will use the next available number.\n\nCard numbers for a mobile credential need not be unique.  They are strings, and are not\nused by Command Centre except for display.\n\nCard numbers for digital IDs are GUIDs.\n\nThis field is mandatory for card types with text or PIV number formats.  If the card type\nhas a text card number format with a regular expression and you supply a card number that\ndoes not match that regex, Command Centre will reject your update.\n\nPIV card numbers must be the same as the card's FASC-N.  PIV-I card numbers must not.\n\nThis field is also mandatory for PIV, PIV-I, tracking tag, GovPass, and Universal Credential\n(`profileCredential`) classes.\n\nOne rule is common across all card types:  you cannot change the number of an existing\ncard or credential.\n"},"cardSerialNumber":{"type":"string","description":"The serial number (CSN, MIFARE UID) of a physical access card as a hex string without a\nleading '0x'.  The number is encoded in the traditional way, with an even number of\nnumbers and the letters from 'A' through 'F', but the '0x' is missing when it comes out\nof the API and it must be missing when you send it back.\n\nThe example shows a seven-byte serial in the order you can expect in a\nGET and should use in a PATCH or POST.  Those on NXP MIFARE cards start with 04 and end\nwith 80 or 90.\n\nFour-byte serial numbers are in the same format, but shorter: `\"EBD62D25\"`, for example.\n\nThis may not be present on very old cards.\n\nThis field was read-only until 7.90.  It is read-write in 8.00 and later.\n"},"issueLevel":{"maximum":15,"minimum":0,"type":"integer","description":"The issue level of a physical access card.  If two cards have the same number\nbut different issue levels, only the one with this issue level will gain access.\n\nIf you leave it blank when creating a card, Command Centre will pick an appropriate value.\n\nIf you increase it when modifying a card, all cards with lower issue levels will stop working.\n\nThe only credential classes for which an issue level is relevant are `card`, PIV, and\nPIV-I.  Some other credential classes currently accept and ignore issue levels, but may\nreject them in a future version.\n"},"status":{"type":"object","properties":{"value":{"type":"string","description":"This card's state, taken from the card type's state set.  The default card\nstate set contains 'Active', 'Disabled (manually)', 'Lost', 'Stolen', and\n'Damaged', or translations of those into the server's language.  Your card state sets may\ndiffer, as they are customisable. [PIV cards](piv) have extra values.\n\nIn addition to the values in the card type's state set, it will be 'Not Yet Activated'\nif the card's activation date is in the future, 'Expired' if its deactivation date has\npassed, or 'Disabled (by inactivity)' if that is the site's policy and the card has\nnot been used at a door.\n\nBecause the value of the `value` field is set by site administrators, you\nshould not use it for programmatically determining whether a card is active.\nUse `type` instead.  Use `value` for display.\n\nWhen creating or updating a card, set `value` to one of the valid card states from the\ncard state set.  Command Centre is not fussy about case.  If you omit it when you\ncreate a card, Command Centre will use the default for the card state set (which is\n'active' for the factory state set).\n\nIf you omit both this and the PIV status when creating or updating a PIV card, or omit\nthis and set the PIV status to 'normal' or 'offline', the server will set this to\n'active'.  Any other PIV status will cause the card to become inactive, regardless of\nwhat you put here.  So you really only need to set this when you are changing the PIV\nstatus to 'normal' or 'offline' but you want to disable the card.  In that case, set\n`status.value` to 'disabled (manually)'.\n"},"type":{"type":"string","description":"This will be 'pending' if the activation date (`from`) is in the future,\n'expired' if its deactivation date (`until`) is in the past, or 'inactive'\nif it is disabled for one of the reasons given in the card state.\n\nNever send `type`:  Command Centre always infers it.\n","readOnly":true,"enum":["pending","active","expired","inactive"]}},"description":"Each card has two status codes:  `value`, and `type`, covered in separate sections below.\n\n`value` is human-readable.  It comes from the _Card State Set_ configured by the site, and\ncould be adjusted according to the card's activation dates.  The REST API and this\ndocument do not cover card state sets because in most cases, the default set is\nsufficient.  See the online help for the Command Centre client if you wish to create your\nown.\n\nThe second field, `type`, comes from a fixed enumeration, and so is better suited than\n`value` for integrations.  Command Centre derives it from the card's state and activation\ndates.\n"},"type":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"}},"description":"The name of the card type from the site configuration, and a link to the card type object.\n\nWhen creating a card, the href must be a card type that makes sense for the other values\nyou placed in this object.\n\nYou cannot change a card's type once it is created.\n"},"invitation":{"type":"object","properties":{"email":{"type":"string","description":"The email address to which Command Centre will send or did send an invitation for this\ncredential.\n"},"mobile":{"type":"string","description":"The telephone number to which Command Centre will send or did send an SMS containing a\nconfirmation code for this invitation.\n"},"singleFactorOnly":{"type":"boolean","description":"If you set this true Command Centre will not require a PIN or fingerprint from the\ncardholder when they enrol.  Be aware that without that second authentication factor,\nzones in modes that require a PIN and readers that always require a second factor will\nnot grant access to the cardholder.\n\n`singleFactorOnly` will only be in the result of a GET if it is true.  If it is false,\nthe field will be missing.\n","default":false},"status":{"type":"string","description":"\n- `sent` means Command Centre is waiting for the user to accept the invitation, either\n  in Gallagher Mobile Connect or another app that uses the Mobile Connect SDK.\n\n- `accepted` means that the credential is ready for use.\n\n- `notSent` means the credential is only a few seconds old or Command Centre is having\n  trouble contacting the cloud.\n\n- `expired` means that Command Centre did not receive a response in time.\n","readOnly":true,"enum":["notSent","sent","expired","accepted"]},"href":{"type":"string","description":"Mobile applications use this URL to accept this invitation.  See the Mobile Connect\nSDK documentation for how to do that in your own applications.\n\nOnly present if `status` is 'sent'.\n","format":"uri-reference","readOnly":true}},"description":"Command Centre will only return this object for a mobile credential, and you should send\nit only when creating one.  In the interests of security you cannot modify the invitation\nblock of an existing credential.  Someone's thumb might be on its way to accept it, after all.\nIf there was something wrong with it you should delete it and start afresh.\n\nWhether you should send `mobile` or `email` when creating a mobile credential depends on\nwhether you are using the Gallagher mobile apps or your own.\n\nIf you specify either `mobile` or `email` to early-version servers you must also supply the\nother so that Command Centre can send both an email invitation and a confirmation SMS.  It\nis an error to only specify one on those servers.\n\nLater versions of Command Centre made the SMS verification optional to better support\ninstallations that use the Gallagher apps but prefer not to depend on cellular connectivity.\nYou do not need to send a mobile number when creating such a credential.\n\nIf you do not give an email address Command Centre cannot send an invitation to the\ncardholder.  It will be up to another application to complete the creation of this\ncredential using the Mobile Connect SDK.\n\nYou should not send a mobile number when creating a credential for use by third-party apps\nthat use the Mobile Connect SDK.  SMS is not supported there.\n\nFor more detail on using the Mobile Connect SDK, including more complete coverage of how\nan email address and mobile number are used in the provisioning process, see its\ndocumentation at [gallaghersecurity.github.io](https://gallaghersecurity.github.io).\n"},"from":{"type":"string","description":"The start of the time period during which this card is active.  If this time is in the\nfuture, the card is not active.\n\nWhen it is not set, Command Centre acts as though it is set to a time in the distant past.\n\nWhen creating a card, leave this property out (or send `null`) to use the card type's\ndefault start time, if the card type has one.  Send an empty string `\"\"` to create the card\nwith no start time even when the card type has a default.  `from` and `until` are treated\nindependently, so leaving out `from` while sending `until` still applies the card type's\ndefault `from`.\n\nWhen modifying a card, send an empty string `\"\"` to reset it.\n\nAny value you send other than a blank string or null must be in RFC 3339 format,\nincluding a timezone.  It must be before midnight on the morning of January 1, 2100 in\nthe server's _local_ time (so servers with positive timezone offsets have maximums\nduring December 31 2099), and it must be less than or equal to the `until` time.  A\nfuture version of Command Centre will clamp too-high values to December 31 2099 and\nreturn a 2xx (success) instead of 400 in that case.\n\nThe server rejects a timestamp that is not in an acceptable format with a 400, whether the\ncard is being created or modified.\n","format":"date-time"},"until":{"type":"string","description":"The end of the time period during which this card is active.  If this time is in the past,\nthe card is not active.\n\nWhen it is not set, Command Centre acts as though it is set to a time in the distant future.\n\nWhen creating a card, leave this property out (or send `null`) to use the card type's\ndefault expiry, if the card type has one: either its fixed end time, or its duration\ncounted from the time the card is created.  Send an empty string `\"\"` to create the card\nwith no end time even when the card type has a default.  `from` and `until` are treated\nindependently, so leaving out `until` while sending `from` still applies the card type's\ndefault `until`.\n\nWhen modifying a card, send an empty string `\"\"` to reset it.\n\nAny value you send other than a blank string or null must be in RFC 3339 format,\nincluding a timezone.  It must be before midnight on the morning of January 1, 2100 in\nthe server's _local_ time (so servers with positive timezone offsets have maximums\nduring December 31 2099), and it must be greater than or equal to the `from` time.  A\nfuture version of Command Centre will clamp too-high values to December 31 2099 and\nreturn a 2xx (success) instead of 400 in that case.\n\nThe server rejects a timestamp that is not in an acceptable format with a 400, whether the\ncard is being created or modified.\n","format":"date-time"},"credentialClass":{"type":"string","description":"This indicates the type of the card.  It comes from an enumeration, and is a reliable way\nof determining the credential's type.\n\nAdded in 8.00.\n\nThe experimental `applePass` was added in 9.10.  Its name may change in future versions.\n\nThe `govPass` credential class will change its name in 9.30.\n","readOnly":true,"enum":["card","digitalId","govPass","mobile","piv","pivi","profileCredential","trackingTag","transact"]},"trace":{"type":"boolean","description":"If set, using this credential will generate an event.\n\nThis field is not in the default set so you will not see it unless you ask for it using\nthe `fields` query parameter.\n\nAdded in 8.30.\n"},"lastPrintedOrEncodedTime":{"type":"string","description":"The date and time this card was last printed or encoded.  It will not come out by\ndefault - you need to ask for it with `fields=cards.lastPrintedOrEncodedTime`.\n\nAdded in 8.40.\n","format":"date-time","readOnly":true},"lastPrintedOrEncodedIssueLevel":{"maximum":15,"minimum":1,"type":"integer","description":"The issue level of this card when it was last printed or encoded, provided it was\nnon-zero.  It will not come out by default - you need to ask for it with\n`fields=cards.lastPrintedOrEncodedIssueLevel`.\n\nAdded in 8.40.\n","readOnly":true},"lastUsedTime":{"description":"When a Gallagher controller last observed the credential in use.\n","type":"string","format":"date-time","readOnly":true},"pin":{"type":"string","description":"This is a write-only field.\nYou can use it in POSTs and PATCHes but the server will not send it to you.\n\nBeing numeric, you might be tempted to send PINs to the server without surrounding\nquotes.  However if you do that, leading zeros will be lost and the resulting behaviour\nis undefined.\n\n8.90 servers will reject your request if the card's `credentialClass` is not `card`,\n`piv`, `pivi`, or `govPass`.  More recent servers will issue a warning in that case, and\nwill not set the PIN, but will allow the rest of the update.\n\nPINs were added to the API in 8.90.\n"},"visitorContractor":{"type":"boolean","description":"This is a credential property only for GovPass, indicating that the enrolled credential is\nfor a visitor / contractor.\n\nIt is a write-once field new to 9.00.\n"},"ownedBySite":{"type":"boolean","description":"This is a credential property only for GovPass, indicating if the site is the owner of the\ncard.\n\nIt is a read-only field new to 9.00.\n","readOnly":true},"credentialId":{"type":"string","description":"Reserved for use by Gallagher applications."},"bleFacilityId":{"type":"string","description":"Reserved for use by Gallagher applications."},"encodingData":{"type":"object","readOnly":true,"properties":{"mifareClassic":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"mifareDesfire":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}},"description":"This block contains links to the calls that return the data you will need to encode\nMIFARE DESFire and Classic cards.  For more on that see the 'Card Encoding' tag.\n\nRead-only:  the server will ignore it if you send it.\n\nAdded in 9.50.\n\nNot returned by default:  ask for it by adding `cards.encodingData` to your `fields`\nquery parameter.\n"},"deviceType":{"type":"string","enum":["applePhone","appleWatch","androidPhone","androidWatch"],"description":"Required when creating a wallet credential.  Either `applePhone` or `appleWatch` when\ncreating an Apple credential, and either `androidPhone` or `androidWatch` for Google.\n\nWallet credentials are part of the Universal Credentials feature added in 9.60.\n"}},"description":"A _card_ is an access credential, including physical cards and mobile (Bluetooth and NFC)\ncredentials and digital IDs.  The server returns it as part of a [cardholder's\ndetails](models#cardholderdetail), and you supply it when creating or modifying a card\nor credential on a cardholder.\n\nEvery card has a type, a status, and a validity period.  Its type determines other fields of\nrelevance, described below.\n\nPIV cards are complex enough to warrant a [tag of their own](piv).\n"}}}}
```

## The CardholderAccessGroup object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderAccessGroup":{"title":"Cardholder access group membership","type":"object","properties":{"href":{"type":"string","description":"This is the href of the cardholder's membership to an access group, not an access group\nitem.\n\nDELETE it to remove this group membership, and use it in the body of a PATCH to a\ncardholder to identify memberships you want to modify.\n\nNote that changing an access group membership with a PATCH will change this href, so do\nnot cache it.\n\nDELETE is the only verb you can use on this URL.  GET returns a 404.\n","format":"uri-reference"},"accessGroup":{"type":"object","description":"An object containing the group's href (which is also a link to its detail page) and,\nwhen sent by the server, the group's name.  You should not send this object when\nmodifying a group membership because you cannot change a group membership's group; you\ncan only change its dates.  But you must send it when adding a new group membership, of\ncourse, because it identifies the cardholder's new group.  Just send the group's href:\ndon't bother with the name.\n\n8.70 and later will not return the link if your operator does not have the privilege to\nview the access group (given by 'View access groups', for example).\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"status":{"type":"object","properties":{"value":{"type":"string","description":"The state of this cardholder's access group membership, in the site's language.  In an\nEnglish locale the value is the same as the type, but capitalised.\n","readOnly":true},"type":{"type":"string","description":"The state of this cardholder's access group membership.\n\nThis will be 'pending' if the activation date is set and in the future,\n'expired' if its deactivation date is set and in the past, or 'active'.\n","readOnly":true,"enum":["pending","expired","active"]}},"description":"The two fields in this block are read-only because they are determined by the `from` and\n`until` dates.\n","readOnly":true},"from":{"type":"string","description":"The start of the time period during which this group membership is active.  If this time\nis in the future, the membership will be inactive.  If null or in the past and `until`\nis null or in the future, the membership will be active.\n\nWhen sending this to a server of version 7.90.883 or earlier, use UTC with a trailing 'Z'.\nMore recent versions understand timezone offsets.\n","format":"date-time"},"until":{"type":"string","description":"The end of the time period during which this group membership is active.  If this time\nis in the past, the membership will be inactive.  If null or in the future and `from` is\nnull or in the past, the membership will be active.\n\nWhen sending this to a server of version 7.90.883 or earlier, use UTC with a trailing 'Z'.\nMore recent versions understand timezone offsets.\n","format":"date-time"}},"description":"An _access group_ is an object in Command Centre.  This section is about a connection between an access group and\na cardholder, called a _membership_.  A cardholder can be a member of many groups, and groups\ncan have any number of members.\n\nLess obvious is that a cardholder can have many memberships to the same group.  This is useful\nbecause a membership has a validity period, expressed with `from` and `until` date-times.\nOutside those moments Command Centre does not regard the cardholder as being a member of the\ngroup.  If there exists one membership with `from` in the past or unset and `until` in the\nfuture or unset, the cardholder is a member.\n\nPresence in an access group affects physical access rights and possession of PDFs, among other\nthings.\n\nThe membership object will come from the server in a cardholder's details if you ask for it, and you send it to\nthe server when modifying a cardholder's group memberships.  All uses are described below.\n"}}}}
```

## The CardholderOperatorGroup object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderOperatorGroup":{"title":"Cardholder operator group membership","description":"An _operator group_ is an object in Command Centre.  The connection between an operator group\nand a cardholder is a _membership_.  A cardholder can be a member of many different operator\ngroups, and operator groups usually have more than one member, but a cardholder can only have\none membership to a given operator group at a time.  This is because an operator group\nmembership, unlike an access group membership, does not have start and end dates.\n\nPresence in an operator group affects software access.  Your REST operator, for example, must\nbe in an operator group that grants privileges otherwise it will receive nothing but 404s.\n\nAdded to the API in 8.50.\n","type":"object","properties":{"href":{"type":"string","description":"DELETE this URL or use it in the `operatorGroups` block of a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-) to remove this operator group\nmembership.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n","format":"uri-reference"},"operatorGroup":{"type":"object","description":"An object containing a link to this operator group's detail page and its name.\n\nThe link will be absent from the results of a GET if your operator does not have the\nprivilege to view the operator group ('View operators' or 'Edit operators', for\nexample).\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}}}}}
```

## The CardholderCompetency object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderCompetency":{"title":"Cardholder competency","description":"A _competency_ is an object in Command Centre with some basic fields like a name and a notice\nperiod.  Its purpose is to allow a site to refuse access to cardholders who do not meet a\nspecial requirement.\n\nThis section describes the link between a cardholder and a competency.  The status of that link\ndetermines whether they \"hold\" the competency for the purposes of access control decisions at\nthe door.  When we talk about updating, adding, or deleting a competency in the cardholder\nAPI, we do not mean the competency object itself, but rather the link a cardholder has to the\ncompetency.\n\nThe link between cardholder and competency is a block in the cardholder detail.  You can\nalso request the server to add it to the results of a cardholder search by putting\n`competencies` in the `fields` parameter.\n\nWhen updating a cardholder's holding of a competency, the fields you send are slightly\ndifferent from what you receive from a cardholder GET:  you do not send read-only blocks\nsuch as `status` and `competency`, and there is a write-only field `enabled` that you can\nsupply to change the status.\n\nYou cannot use a PATCH to move the status, times, comment, and credit to a different\ncompetency.  If you need to do that, delete the cardholder's existing competency and give\nthem a new one.  You can do that in one PATCH.\n\nA cardholder can have only one link to a given competency.  Attempting to give a cardholder\na competency a second time will either fail or raise a stateful alarm and succeed, depending\non your version of Command Centre.\n","type":"object","properties":{"href":{"type":"string","description":"This is the URL of the cardholder's connection to a competency, not the URL of the\ncompetency itself.  Use it as the target of a DELETE to remove a cardholder's\ncompetency, or in the body of a cardholder PATCH to modify it.\n\nDELETE is the only verb you can use on this URL.  GET will return a 404.\n","format":"uri-reference","readOnly":true},"competency":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}},"description":"This contains the competency's name and its href.\n\nAs ever, do not bother putting `name` in the body of a POST or PATCH.  The server will\nignore it.\n"},"status":{"type":"object","properties":{"value":{"type":"string"},"type":{"type":"string"}},"description":"This object contains two strings.  Both are read-only, so do not specify them when\nassigning or updating a cardholder's competency.  `value` is taken from the site's\nlanguage pack, suitable for display. `type` comes from a fixed enumeration.  It will be\n`expiryDue` or `active` when the cardholder carries this competency; anything else means\nno.  A fuller explanation follows.\n\nA competency can be disabled, expired, both, or neither.  Whether it is _enabled_ is a\nflag on the cardholder's holding of the competency.  Whether it is _expired_ is derived from an expiry\ntimestamp (accurate to the second):  if it is in the past, Command Centre considers the\ncompetency expired.\n\nA competency can also have an `enablement` date.  If that date (timestamp) passes while the\ncompetency is disabled, Command Centre will enable the competency.  It will leave the date on\nthe item for future reference, though it will not affect the competency again.\n\nIf the competency is disabled, the status `type` will be `inactive` when there is no\nenable date or it is in the past, and `pending` when the enable date is in the future\n(i.e., there is an automatic re-enablement coming).\n\nIf the competency is not disabled, the `expiry` time is important.  If it is in the past,\n`type` will be `expired`.\n\nAll of those cases are negative.  Two remain, when our cardholder is blessed with an\nenabled and active competency.  `type` will be `expiryDue` if the `expires` time is in the\nfuture but within the competency's advance notice period, or `active` if the `expires`\ntime is beyond the advance notice period or not set at all.\n\nYou can see and set the enabled flag, the enable date, and the expiry date via this\nAPI.\n\nWhen creating a cardholder or updating a competency on an existing cardholder, you should\nset the `enabled` field one way or the other, and the `enablement` and `expiry` dates if\nyou wish.  They will determine the contents of this status block.\n\nHere it is in table form.  The first two rows are the positive cases, when Command Centre\nwould grant access to a competency-enforced zone.\n\n| Enabled flag | Enablement date | Expiry date | `status.type`\n| ------------ | -------------- | --------| ----- |\n| true | - | Far future | active |\n| true | - | Near future | expiryDue |\n| true | - | Past | expired |\n| false | Future | - | pending |\n| false | Past | - | inactive |\n| false | Unset | - | inactive |\n","readOnly":true},"disabled":{"type":"boolean","readOnly":true,"deprecated":true,"description":"Do not use this field.  Instead, take the state of a cardholder's competency from\n`status.type`.  This field is misleading on its own:  even when it is true, the\ncompetency might still be inactive.\n"},"enabled":{"type":"boolean","writeOnly":true,"description":"This is a write-only field.  You will not receive it from the GET.  It changes the\ncompetency between enabled (status type `expired`, `expiryDue`, or `active`) and\ndisabled (status type `inactive` or `pending`).  Set it to false in a PATCH if you want\nto disable the competency now, particularly if you are setting a future enablement date.\n"},"expiryWarning":{"type":"string","description":"The time at which the cardholder will (or did) receive a warning about the\ncompetency expiring.  If this time is set and in the past but the competency has\nnot yet expired and is still enabled, the status type will be `expiryDue`.\n","format":"date-time","readOnly":true},"expiry":{"type":"string","description":"The time at which the competency will expire.  If this time is set, in the past, and the\ncompetency is enabled, status type will be `expired`.\n","format":"date-time"},"enablement":{"type":"string","description":"The time at which the competency will be re-enabled.  If set and in the future, and the\ncompetency is disabled, the status type will be `pending`.\n\nYou can set this on an enabled competency but it has no effect there, so with this field\nyou would generally also set `enabled: false`.\n","format":"date-time"},"comment":{"type":"string","description":"The comment appears in the management clients when viewing the cardholder.\n"},"limitedCredit":{"type":"boolean","description":"If false, Command Centre's 'Pre-pay Car Parking' feature (available under its own licence)\nwill not reduce the current credit.\n\nThis field will be in the results if its value is true.\n"},"credit":{"type":"integer","description":"The balance, or amount of credit left on this competency for use by Pre-pay Car Parking.\nIt can be negative.\n\nThis field will be in the results if its value is not zero.\n"}}}}}}
```

## The CardholderRelationship object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderRelationship":{"title":"Cardholder relationship","description":"A _role_ is an object in Command Centre.  Roles are usually named using nouns such as\n'supervisor', 'manager', or 'team leader'.\n\nThe operator clients and the REST API allow you to create a link between two\ncardholders, called a relationship, using a role.  The link is directional:  we\nrefer to the cardholder who 'has' the role as the child, and the cardholder who\nperforms or 'is' the role as the parent.\n\nA parent can perform a role for any number of child cardholders, but a child can only have one\nrelationship (parent) for each role.  Command Centre will reject your submission if you try to\ncreate a relationship when one already exists for the same child and role.\n\nFor example, a role on your system might be 'supervisor'.  A cardholder can be a supervisor\nfor any number of others, but will only have one supervisor.\n\nLoops are possible:  two cardholders can supervise each other.\n\nThe REST API manages relationships through the child cardholder.  You can create them at the\nsame time as creating the child in a POST, or add them later in a PATCH.\n\nThere is currently no way to list all a cardholder's children in one request (everyone a\nparticular cardholder is supervising, for example).  You would achieve that by iterating\nthrough all cardholders, after re-reading the efficiency tips, and checking their\nrelationships - quite easily done in JSONPath.\n\nThis section describes the object you receive in a cardholder's detail page and you will send\nin a POST or PATCH.  The child cardholder does not appear in it because he or she is\nidentified by the URL of the request.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the href of the link between two cardholders.  DELETE it, or put it in\n`relationships.remove.href` of a PATCH directed at the child cardholder, to sever the\nrelationship.  Specify it in `relationships.update.href` of a PATCH to the child\ncardholder to update the relationship.\n\nDo not specify it when creating a new relationship.  The server generates it for you.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"role":{"type":"object","description":"This is the role that the parent identified in the `cardholder` block performs for the\ncardholder identified by the request URL.\n\nOnce set, this cannot be changed.  Command Centre will ignore it if you send it\nin an update PATCH.  If you need to swap a parent from one role to another, send\nan add and a delete in the same PATCH.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"cardholder":{"type":"object","description":"The href and name of the cardholder that performs this role.\n\nThe three name fields are read-only:  Command Centre sends them to you in the body of a\nGET but will ignore them if you send them in the body of a POST or PATCH.\n\nThis block and the href in it are unnecessary when deleting a relationship.  The href is\nrequired when creating one, and optional when updating, but strongly advised since the\ncardholder is the only thing about a relationship you can change.\n\n`firstName` and `lastName` appeared in 8.20.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for the parent cardholder."},"firstName":{"type":"string","readOnly":true},"lastName":{"type":"string","readOnly":true}}}}}}}}
```

## The CardholderLocker object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderLocker":{"title":"Cardholder locker","description":"These appear in an array in a cardholder detail, showing the cardholder's allocated lockers.\nEach allocation has `from` and `until` dates, much like cards and access group memberships,\noutside of which the allocation is inactive.\n\nA locker can have allocations to more than one cardholder, with separate or overlapping\nperiods.  Unlike access groups, however, one cardholder cannot have more than one allocation\nto the same locker.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this to end a cardholder's use of a locker, or use it to identify the\nallocation you wish to modify in a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-).\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"locker":{"description":"The href in this object is a link to the allocated locker, and is the identifier to use\nwhen allocating the same locker to another cardholder.\n\nThe object also contains the name and short name of the locker, and the name and\nidentifying href of its bank.\n","type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for a locker."},"shortName":{"type":"string","readOnly":true},"lockerBank":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"from":{"description":"The start of the time period during which the cardholder has access to this locker.\n\nSend an empty string `\"\"` to reset it.\n","type":"string","format":"date-time"},"until":{"description":"The end of the time period during which the cardholder has access to this locker.\n\nSend an empty string `\"\"` to reset it, making the allocation permanent.\n","type":"string","format":"date-time"}}}}}}
```

## The CardholderElevatorGroup object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderElevatorGroup":{"title":"Cardholder elevator group","description":"These appear in an array in a cardholder detail, showing the cardholder's elevator group\nproperties, and can go into the body of a POST or PATCH to set a cardholder's elevator group\nproperties.\n\nA cardholder can have one default floor per elevator group. The elevator system will\nprepare a car to carry that cardholder to the access zone shown here when the cardholder\nbadges a card at an appropriately configured kiosk.\n\nElevator system features can be activated by enabling the feature for an elevator group.\nFor example, 'VIP features' gives exclusive access to an elevator car to the passenger.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"The href of this cardholder's elevator group entry.  DELETE this to remove it from the\ncardholder.\n"},"elevatorGroup":{"type":"object","description":"The href and name of the elevator group for which this cardholder has a default\nfloor or passenger type.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"accessZone":{"type":"object","description":"The href and name of the access zone (floor) to which this cardholder is most\nlikely to want to travel after entering the group's main elevator lobby. This \nproperty will be missing if the cardholder does not have a default floor for this elevator group.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"enableCaptureFeatures":{"type":"boolean","description":"Cardholders can select and recall specific elevators to specific floors using\na kiosk. Once captured, the elevator car can be placed on independent service to\ngive users control of the car to clean the interior or perform maintenance.\n"},"enableCodeBlueFeatures":{"type":"boolean","description":"A special elevator mode which is commonly found in hospitals. It allows an elevator\nto be summoned to any floor for use in an emergency situation.\n"},"enableExpressFeatures":{"type":"boolean","description":"Allows the cardholder to program selected elevators to cycle continuously between two\nfloors for a pre-determined duration. For example, this feature can help hotels transport\nfood efficiently from their kitchen to a ballroom on another floor. You can also prevent\nother guests from boarding to provide your banquet guests with VIP treatment.\n"},"enableServiceFeatures":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop\nto their destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableService2Features":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop\nto their destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableService3Features":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop to\ntheir destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableVipFeatures":{"type":"boolean","description":"VIP operation allows cardholders to swipe a card or enter a PIN to isolate the elevator\nand provide uninterrupted access to their designated floor.\n"}}}}}}
```

## The CardholderPOST object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderPOST":{"title":"Cardholder POST","description":"This is part of the model of a POST body that creates a cardholder.  It does not contain\nevery field you can set when creating a cardholder, but shows the division (which is\nmandatory) and an access group, an access card, a supervisor, a competency, two personal\ndata fields, two lockers, and two elevator groups.\n\nThere are more fields on a cardholder than shown here.  For a complete list please see the\nschema for the detailed [cardholder object](models#cardholderdetail) that you receive\nfrom a cardholder href.\n","required":["division"],"properties":{"firstName":{"type":"string","description":"You must supply either this or the last name when creating a cardholder.\n\nThe maximum length of a cardholder's first name in version 9.50 is 50 characters.\n"},"lastName":{"type":"string","description":"You must supply either this or the first name when creating a cardholder.\n\nThe maximum length of a cardholder's last name in version 9.50 is 50 characters.\n"},"shortName":{"type":"string"},"description":{"type":"string"},"authorised":{"description":"Remember to set this true, as shown here in the POST, or later in a PATCH.  Otherwise your\nnew cardholder will never get through a door.\n","type":"boolean"},"division":{"type":"object","description":"Mandatory when creating any cardholder.  In this example, we want all students\nin division 5387.\n"},"@email":{"description":"An example PDF value.  In this example, access group 352 must include a PDF\ncalled 'email' otherwise this will appear to have no effect.\n","type":"string"},"@headshot":{"description":"An example image PDF encoded to Base64.  Access group 352 must include this PDF as well.\nAs a quick visual check on your encoding, JPEGs start with `/9j/`.\n","type":"string"},"personalDataDefinitions":{"description":"This is how you set and unset the notifications flags on PDFs.  If you do not do it here\nwhen you first give a cardholder a PDF, it will come from the PDF's definition.\n","type":"array","items":{"$ref":"#/components/schemas/CardholderPDF"}},"cards":{"description":"This example creates one physical card of type 600 with a PIN and a system-generated card\nnumber, and\nanother of type 654 which--judging by the invitation block--must be a mobile credential.\nCommand Centre will send an invitation to Nick at those coordinates.\n\nCard PINs were added to the API in 8.90.\n","type":"array","items":{"$ref":"#/components/schemas/CardholderCard"}},"accessGroups":{"type":"array","items":{"$ref":"#/components/schemas/CardholderAccessGroup"},"description":"Here you can add the access groups necessary to give your new cardholder the\nPDFs and access he or she needs.  In this example we set the activation date of\nthe access group membership to the first of January 2019.\n"},"operatorGroups":{"type":"array","items":{"$ref":"#/components/schemas/CardholderOperatorGroup"},"description":"Here you can add the operator groups necessary to give your new cardholder the\nsoftware access he or she needs.  Added in 8.50.\n"},"competencies":{"type":"array","items":{"$ref":"#/components/schemas/CardholderCompetency"},"description":"In this example we are giving our new cardholder a disabled competency, set to enable in\nJanuary 2019.\n"},"notes":{"type":"string"},"notifications":{"type":"object","description":"You can set or update any of the three fields in this block.","properties":{"enabled":{"type":"boolean"},"from":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/CardholderRelationship"},"description":"Here you would set the cardholders who will perform roles for this cardholder.\n\nThe example shows that this cardholder will have cardholder 5398 performing role 5396.\n\nRemember that you can supply an array of these objects if your cardholder is having more\nthan one role filled.\n"},"lockers":{"type":"array","description":"Here you set all the cardholder's locker assignments.  Ensure you are only attempting to\ngive your cardholder a locker according to site policy (one locker per locker bank, for\nexample), otherwise the POST will fail.\n\nThe example shows our cardholder receiving two lockers.\n","items":{"$ref":"#/components/schemas/CardholderLocker"}},"elevatorGroups":{"type":"array","description":"Here you set all the new cardholder's default elevator floors and passenger types. Passenger type properties\nare false by default.\n\nThe example shows our cardholder receiving a default floor for the first elevator group,\nwith the Code Blue feature enabled in the second group.\n\nAdded in 8.50.\n","items":{"$ref":"#/components/schemas/CardholderElevatorGroup"}}}},"CardholderPDF":{"title":"Cardholder PDF","description":"A personal data definition and its value for a cardholder.  Each definition is an object\ncontaining one property named after the PDF (plus a leading '@'), which in turn contains its\nvalue and notifications flag for the containing cardholder and an object containing some of\nthe PDF definition's basic fields.\n\nThis is returned as part of a [cardholder](models#cardholderdetail), and you can send it\nin a [POST](models#cardholderpost) or a\n[PATCH](models#cardholderpatch) to set the PDF's value and notification flag for\na cardholder.  The server will ignore the `definition` block if you send it back.  It uses the\nname of the block (minus its leading `@`) to find the PDF to change.\n\nWhile you can use this structure to change the value of a cardholder's PDF, it may be simpler\nto put a property in the root of the payload named after the PDF with a leading '@'.\n","type":"object","additionalProperties":{"$ref":"#/components/schemas/CardholderPDFContent"}},"CardholderPDFContent":{"title":"Cardholder PDF content","type":"object","properties":{"href":{"type":"string","description":"GET this link to receive this cardholder's value for this PDF.  If it is an image you will\nreceive the raw image data with an appropriate content-type.  A browser will render it\ncorrectly.\n\nIf the PDF is not an image the content type will be text/plain, encoded (like\neverything else in this API) as UTF-8.  But you should only use it for image PDFs\nbecause:\n\n* Values for scalar PDF types (everything except images) are also given to you in the\n  `value` field in this object, described below.\n\n* The format of date PDFs varies with the Command Centre version.  Old servers return\n  it in a format that depends on the server's locale.  This was a bug.  Newer servers\n  use ISO 8601.\n\n* If you learn this URL while a cardholder has the PDF, then the cardholder loses\n  it, then you GET the URL, results will vary depending on the server version.  The\n  correct result is a 404, and if the PDF is an image or the server is recent you\n  will see that.  But old servers may return a blank string or even a 500 for\n  non-image PDFs.\n\nThis field will be absent if the cardholder does not have a value for the PDF.\n\nIt is read-only:  do not send it in a PATCH or POST.\n","format":"uri-reference","readOnly":true},"definition":{"type":"object","properties":{"href":{"type":"string","description":"This is the href of the PDF's definition, common to all cardholders who hold a value\nfor this PDF.\n","format":"uri-reference"},"name":{"type":"string","description":"The PDF's name, without an '@' prefix.\n"},"id":{"type":"string","description":"Short alphanumeric identifier used elsewhere in the API to filter cardholder searches\nand add PDF values to alarm and event GETs.\n"},"type":{"type":"string","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]}},"description":"The definition object is read-only:  do not send it in a PATCH or POST.\n","readOnly":true},"value":{"description":"In a GET response for text, numeric, and date PDFs this will be a scalar containing the\nvalue, but for image PDFs it will be an object containing a copy of the `href` field\nabove.  For date PDFs the string will comply with RFC 3339, but may or may not contain a\ntime depending on the version of Command Centre.  Newer versions omit the `T` separator\nand everything after it.  If there, it will be midnight UTC.\n\nIn versions up to and including 8.60, if a cardholder did not have an image PDF captured\n(in other words they were a member of an access group that included an image PDF, but they\ndid not have a value for it) the API returned the string 'Not captured' in the `value`\nfield.  Versions 8.70 and later will not return the `value` field at all if there is no image.\n\nIn a POST or PATCH send text PDFs (including dates) as strings, numeric PDFs as numbers or\nstrings that parse to numbers, and image data Base64-encoded into a string.\n","oneOf":[{"type":"integer","title":"Numeric","description":"The scalar value of the numeric PDF."},{"type":"string","title":"Text or date","description":"The scalar value of the text or date PDF."},{"type":"object","title":"Image","description":"An object containing an href which, when requested from the server, returns the\nimage PDF.  The server does not transcode images:  it will arrive as the same\ncontent type as uploaded.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"Only present for image PDFs, this will be a copy of the href field in the parent\nobject.  When requested from the server it will return the image PDF as it was\nuploaded.\n"}}}]},"notifications":{"type":"boolean","description":"In a GET response, this will only appear for email and mobile PDF types.  In a POST or\nPATCH, it only makes sense for the same types.\n\nIf true, cardholder notifications will go to the telephone number or email address held by\nthis PDF.  Cardholders can have their notifications go to as many contacts as they wish.\n"}}},"CardholderCard":{"title":"Cardholder card","type":"object","properties":{"href":{"type":"string","readOnly":true,"description":"DELETE this link to delete a card.\n\nDo not specify it when creating a card.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404 in the\ncurrent versions of Command Centre.\n","format":"uri-reference"},"number":{"type":"string","description":"For a physical access card, this is its card number.  It must be unique across all cards\nof the same card type.  If you leave it blank when creating a card of a type that has a\ndecimal number format, Command Centre will use the next available number.\n\nCard numbers for a mobile credential need not be unique.  They are strings, and are not\nused by Command Centre except for display.\n\nCard numbers for digital IDs are GUIDs.\n\nThis field is mandatory for card types with text or PIV number formats.  If the card type\nhas a text card number format with a regular expression and you supply a card number that\ndoes not match that regex, Command Centre will reject your update.\n\nPIV card numbers must be the same as the card's FASC-N.  PIV-I card numbers must not.\n\nThis field is also mandatory for PIV, PIV-I, tracking tag, GovPass, and Universal Credential\n(`profileCredential`) classes.\n\nOne rule is common across all card types:  you cannot change the number of an existing\ncard or credential.\n"},"cardSerialNumber":{"type":"string","description":"The serial number (CSN, MIFARE UID) of a physical access card as a hex string without a\nleading '0x'.  The number is encoded in the traditional way, with an even number of\nnumbers and the letters from 'A' through 'F', but the '0x' is missing when it comes out\nof the API and it must be missing when you send it back.\n\nThe example shows a seven-byte serial in the order you can expect in a\nGET and should use in a PATCH or POST.  Those on NXP MIFARE cards start with 04 and end\nwith 80 or 90.\n\nFour-byte serial numbers are in the same format, but shorter: `\"EBD62D25\"`, for example.\n\nThis may not be present on very old cards.\n\nThis field was read-only until 7.90.  It is read-write in 8.00 and later.\n"},"issueLevel":{"maximum":15,"minimum":0,"type":"integer","description":"The issue level of a physical access card.  If two cards have the same number\nbut different issue levels, only the one with this issue level will gain access.\n\nIf you leave it blank when creating a card, Command Centre will pick an appropriate value.\n\nIf you increase it when modifying a card, all cards with lower issue levels will stop working.\n\nThe only credential classes for which an issue level is relevant are `card`, PIV, and\nPIV-I.  Some other credential classes currently accept and ignore issue levels, but may\nreject them in a future version.\n"},"status":{"type":"object","properties":{"value":{"type":"string","description":"This card's state, taken from the card type's state set.  The default card\nstate set contains 'Active', 'Disabled (manually)', 'Lost', 'Stolen', and\n'Damaged', or translations of those into the server's language.  Your card state sets may\ndiffer, as they are customisable. [PIV cards](piv) have extra values.\n\nIn addition to the values in the card type's state set, it will be 'Not Yet Activated'\nif the card's activation date is in the future, 'Expired' if its deactivation date has\npassed, or 'Disabled (by inactivity)' if that is the site's policy and the card has\nnot been used at a door.\n\nBecause the value of the `value` field is set by site administrators, you\nshould not use it for programmatically determining whether a card is active.\nUse `type` instead.  Use `value` for display.\n\nWhen creating or updating a card, set `value` to one of the valid card states from the\ncard state set.  Command Centre is not fussy about case.  If you omit it when you\ncreate a card, Command Centre will use the default for the card state set (which is\n'active' for the factory state set).\n\nIf you omit both this and the PIV status when creating or updating a PIV card, or omit\nthis and set the PIV status to 'normal' or 'offline', the server will set this to\n'active'.  Any other PIV status will cause the card to become inactive, regardless of\nwhat you put here.  So you really only need to set this when you are changing the PIV\nstatus to 'normal' or 'offline' but you want to disable the card.  In that case, set\n`status.value` to 'disabled (manually)'.\n"},"type":{"type":"string","description":"This will be 'pending' if the activation date (`from`) is in the future,\n'expired' if its deactivation date (`until`) is in the past, or 'inactive'\nif it is disabled for one of the reasons given in the card state.\n\nNever send `type`:  Command Centre always infers it.\n","readOnly":true,"enum":["pending","active","expired","inactive"]}},"description":"Each card has two status codes:  `value`, and `type`, covered in separate sections below.\n\n`value` is human-readable.  It comes from the _Card State Set_ configured by the site, and\ncould be adjusted according to the card's activation dates.  The REST API and this\ndocument do not cover card state sets because in most cases, the default set is\nsufficient.  See the online help for the Command Centre client if you wish to create your\nown.\n\nThe second field, `type`, comes from a fixed enumeration, and so is better suited than\n`value` for integrations.  Command Centre derives it from the card's state and activation\ndates.\n"},"type":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"}},"description":"The name of the card type from the site configuration, and a link to the card type object.\n\nWhen creating a card, the href must be a card type that makes sense for the other values\nyou placed in this object.\n\nYou cannot change a card's type once it is created.\n"},"invitation":{"type":"object","properties":{"email":{"type":"string","description":"The email address to which Command Centre will send or did send an invitation for this\ncredential.\n"},"mobile":{"type":"string","description":"The telephone number to which Command Centre will send or did send an SMS containing a\nconfirmation code for this invitation.\n"},"singleFactorOnly":{"type":"boolean","description":"If you set this true Command Centre will not require a PIN or fingerprint from the\ncardholder when they enrol.  Be aware that without that second authentication factor,\nzones in modes that require a PIN and readers that always require a second factor will\nnot grant access to the cardholder.\n\n`singleFactorOnly` will only be in the result of a GET if it is true.  If it is false,\nthe field will be missing.\n","default":false},"status":{"type":"string","description":"\n- `sent` means Command Centre is waiting for the user to accept the invitation, either\n  in Gallagher Mobile Connect or another app that uses the Mobile Connect SDK.\n\n- `accepted` means that the credential is ready for use.\n\n- `notSent` means the credential is only a few seconds old or Command Centre is having\n  trouble contacting the cloud.\n\n- `expired` means that Command Centre did not receive a response in time.\n","readOnly":true,"enum":["notSent","sent","expired","accepted"]},"href":{"type":"string","description":"Mobile applications use this URL to accept this invitation.  See the Mobile Connect\nSDK documentation for how to do that in your own applications.\n\nOnly present if `status` is 'sent'.\n","format":"uri-reference","readOnly":true}},"description":"Command Centre will only return this object for a mobile credential, and you should send\nit only when creating one.  In the interests of security you cannot modify the invitation\nblock of an existing credential.  Someone's thumb might be on its way to accept it, after all.\nIf there was something wrong with it you should delete it and start afresh.\n\nWhether you should send `mobile` or `email` when creating a mobile credential depends on\nwhether you are using the Gallagher mobile apps or your own.\n\nIf you specify either `mobile` or `email` to early-version servers you must also supply the\nother so that Command Centre can send both an email invitation and a confirmation SMS.  It\nis an error to only specify one on those servers.\n\nLater versions of Command Centre made the SMS verification optional to better support\ninstallations that use the Gallagher apps but prefer not to depend on cellular connectivity.\nYou do not need to send a mobile number when creating such a credential.\n\nIf you do not give an email address Command Centre cannot send an invitation to the\ncardholder.  It will be up to another application to complete the creation of this\ncredential using the Mobile Connect SDK.\n\nYou should not send a mobile number when creating a credential for use by third-party apps\nthat use the Mobile Connect SDK.  SMS is not supported there.\n\nFor more detail on using the Mobile Connect SDK, including more complete coverage of how\nan email address and mobile number are used in the provisioning process, see its\ndocumentation at [gallaghersecurity.github.io](https://gallaghersecurity.github.io).\n"},"from":{"type":"string","description":"The start of the time period during which this card is active.  If this time is in the\nfuture, the card is not active.\n\nWhen it is not set, Command Centre acts as though it is set to a time in the distant past.\n\nWhen creating a card, leave this property out (or send `null`) to use the card type's\ndefault start time, if the card type has one.  Send an empty string `\"\"` to create the card\nwith no start time even when the card type has a default.  `from` and `until` are treated\nindependently, so leaving out `from` while sending `until` still applies the card type's\ndefault `from`.\n\nWhen modifying a card, send an empty string `\"\"` to reset it.\n\nAny value you send other than a blank string or null must be in RFC 3339 format,\nincluding a timezone.  It must be before midnight on the morning of January 1, 2100 in\nthe server's _local_ time (so servers with positive timezone offsets have maximums\nduring December 31 2099), and it must be less than or equal to the `until` time.  A\nfuture version of Command Centre will clamp too-high values to December 31 2099 and\nreturn a 2xx (success) instead of 400 in that case.\n\nThe server rejects a timestamp that is not in an acceptable format with a 400, whether the\ncard is being created or modified.\n","format":"date-time"},"until":{"type":"string","description":"The end of the time period during which this card is active.  If this time is in the past,\nthe card is not active.\n\nWhen it is not set, Command Centre acts as though it is set to a time in the distant future.\n\nWhen creating a card, leave this property out (or send `null`) to use the card type's\ndefault expiry, if the card type has one: either its fixed end time, or its duration\ncounted from the time the card is created.  Send an empty string `\"\"` to create the card\nwith no end time even when the card type has a default.  `from` and `until` are treated\nindependently, so leaving out `until` while sending `from` still applies the card type's\ndefault `until`.\n\nWhen modifying a card, send an empty string `\"\"` to reset it.\n\nAny value you send other than a blank string or null must be in RFC 3339 format,\nincluding a timezone.  It must be before midnight on the morning of January 1, 2100 in\nthe server's _local_ time (so servers with positive timezone offsets have maximums\nduring December 31 2099), and it must be greater than or equal to the `from` time.  A\nfuture version of Command Centre will clamp too-high values to December 31 2099 and\nreturn a 2xx (success) instead of 400 in that case.\n\nThe server rejects a timestamp that is not in an acceptable format with a 400, whether the\ncard is being created or modified.\n","format":"date-time"},"credentialClass":{"type":"string","description":"This indicates the type of the card.  It comes from an enumeration, and is a reliable way\nof determining the credential's type.\n\nAdded in 8.00.\n\nThe experimental `applePass` was added in 9.10.  Its name may change in future versions.\n\nThe `govPass` credential class will change its name in 9.30.\n","readOnly":true,"enum":["card","digitalId","govPass","mobile","piv","pivi","profileCredential","trackingTag","transact"]},"trace":{"type":"boolean","description":"If set, using this credential will generate an event.\n\nThis field is not in the default set so you will not see it unless you ask for it using\nthe `fields` query parameter.\n\nAdded in 8.30.\n"},"lastPrintedOrEncodedTime":{"type":"string","description":"The date and time this card was last printed or encoded.  It will not come out by\ndefault - you need to ask for it with `fields=cards.lastPrintedOrEncodedTime`.\n\nAdded in 8.40.\n","format":"date-time","readOnly":true},"lastPrintedOrEncodedIssueLevel":{"maximum":15,"minimum":1,"type":"integer","description":"The issue level of this card when it was last printed or encoded, provided it was\nnon-zero.  It will not come out by default - you need to ask for it with\n`fields=cards.lastPrintedOrEncodedIssueLevel`.\n\nAdded in 8.40.\n","readOnly":true},"lastUsedTime":{"description":"When a Gallagher controller last observed the credential in use.\n","type":"string","format":"date-time","readOnly":true},"pin":{"type":"string","description":"This is a write-only field.\nYou can use it in POSTs and PATCHes but the server will not send it to you.\n\nBeing numeric, you might be tempted to send PINs to the server without surrounding\nquotes.  However if you do that, leading zeros will be lost and the resulting behaviour\nis undefined.\n\n8.90 servers will reject your request if the card's `credentialClass` is not `card`,\n`piv`, `pivi`, or `govPass`.  More recent servers will issue a warning in that case, and\nwill not set the PIN, but will allow the rest of the update.\n\nPINs were added to the API in 8.90.\n"},"visitorContractor":{"type":"boolean","description":"This is a credential property only for GovPass, indicating that the enrolled credential is\nfor a visitor / contractor.\n\nIt is a write-once field new to 9.00.\n"},"ownedBySite":{"type":"boolean","description":"This is a credential property only for GovPass, indicating if the site is the owner of the\ncard.\n\nIt is a read-only field new to 9.00.\n","readOnly":true},"credentialId":{"type":"string","description":"Reserved for use by Gallagher applications."},"bleFacilityId":{"type":"string","description":"Reserved for use by Gallagher applications."},"encodingData":{"type":"object","readOnly":true,"properties":{"mifareClassic":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"mifareDesfire":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}},"description":"This block contains links to the calls that return the data you will need to encode\nMIFARE DESFire and Classic cards.  For more on that see the 'Card Encoding' tag.\n\nRead-only:  the server will ignore it if you send it.\n\nAdded in 9.50.\n\nNot returned by default:  ask for it by adding `cards.encodingData` to your `fields`\nquery parameter.\n"},"deviceType":{"type":"string","enum":["applePhone","appleWatch","androidPhone","androidWatch"],"description":"Required when creating a wallet credential.  Either `applePhone` or `appleWatch` when\ncreating an Apple credential, and either `androidPhone` or `androidWatch` for Google.\n\nWallet credentials are part of the Universal Credentials feature added in 9.60.\n"}},"description":"A _card_ is an access credential, including physical cards and mobile (Bluetooth and NFC)\ncredentials and digital IDs.  The server returns it as part of a [cardholder's\ndetails](models#cardholderdetail), and you supply it when creating or modifying a card\nor credential on a cardholder.\n\nEvery card has a type, a status, and a validity period.  Its type determines other fields of\nrelevance, described below.\n\nPIV cards are complex enough to warrant a [tag of their own](piv).\n"},"CardholderAccessGroup":{"title":"Cardholder access group membership","type":"object","properties":{"href":{"type":"string","description":"This is the href of the cardholder's membership to an access group, not an access group\nitem.\n\nDELETE it to remove this group membership, and use it in the body of a PATCH to a\ncardholder to identify memberships you want to modify.\n\nNote that changing an access group membership with a PATCH will change this href, so do\nnot cache it.\n\nDELETE is the only verb you can use on this URL.  GET returns a 404.\n","format":"uri-reference"},"accessGroup":{"type":"object","description":"An object containing the group's href (which is also a link to its detail page) and,\nwhen sent by the server, the group's name.  You should not send this object when\nmodifying a group membership because you cannot change a group membership's group; you\ncan only change its dates.  But you must send it when adding a new group membership, of\ncourse, because it identifies the cardholder's new group.  Just send the group's href:\ndon't bother with the name.\n\n8.70 and later will not return the link if your operator does not have the privilege to\nview the access group (given by 'View access groups', for example).\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"status":{"type":"object","properties":{"value":{"type":"string","description":"The state of this cardholder's access group membership, in the site's language.  In an\nEnglish locale the value is the same as the type, but capitalised.\n","readOnly":true},"type":{"type":"string","description":"The state of this cardholder's access group membership.\n\nThis will be 'pending' if the activation date is set and in the future,\n'expired' if its deactivation date is set and in the past, or 'active'.\n","readOnly":true,"enum":["pending","expired","active"]}},"description":"The two fields in this block are read-only because they are determined by the `from` and\n`until` dates.\n","readOnly":true},"from":{"type":"string","description":"The start of the time period during which this group membership is active.  If this time\nis in the future, the membership will be inactive.  If null or in the past and `until`\nis null or in the future, the membership will be active.\n\nWhen sending this to a server of version 7.90.883 or earlier, use UTC with a trailing 'Z'.\nMore recent versions understand timezone offsets.\n","format":"date-time"},"until":{"type":"string","description":"The end of the time period during which this group membership is active.  If this time\nis in the past, the membership will be inactive.  If null or in the future and `from` is\nnull or in the past, the membership will be active.\n\nWhen sending this to a server of version 7.90.883 or earlier, use UTC with a trailing 'Z'.\nMore recent versions understand timezone offsets.\n","format":"date-time"}},"description":"An _access group_ is an object in Command Centre.  This section is about a connection between an access group and\na cardholder, called a _membership_.  A cardholder can be a member of many groups, and groups\ncan have any number of members.\n\nLess obvious is that a cardholder can have many memberships to the same group.  This is useful\nbecause a membership has a validity period, expressed with `from` and `until` date-times.\nOutside those moments Command Centre does not regard the cardholder as being a member of the\ngroup.  If there exists one membership with `from` in the past or unset and `until` in the\nfuture or unset, the cardholder is a member.\n\nPresence in an access group affects physical access rights and possession of PDFs, among other\nthings.\n\nThe membership object will come from the server in a cardholder's details if you ask for it, and you send it to\nthe server when modifying a cardholder's group memberships.  All uses are described below.\n"},"CardholderOperatorGroup":{"title":"Cardholder operator group membership","description":"An _operator group_ is an object in Command Centre.  The connection between an operator group\nand a cardholder is a _membership_.  A cardholder can be a member of many different operator\ngroups, and operator groups usually have more than one member, but a cardholder can only have\none membership to a given operator group at a time.  This is because an operator group\nmembership, unlike an access group membership, does not have start and end dates.\n\nPresence in an operator group affects software access.  Your REST operator, for example, must\nbe in an operator group that grants privileges otherwise it will receive nothing but 404s.\n\nAdded to the API in 8.50.\n","type":"object","properties":{"href":{"type":"string","description":"DELETE this URL or use it in the `operatorGroups` block of a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-) to remove this operator group\nmembership.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n","format":"uri-reference"},"operatorGroup":{"type":"object","description":"An object containing a link to this operator group's detail page and its name.\n\nThe link will be absent from the results of a GET if your operator does not have the\nprivilege to view the operator group ('View operators' or 'Edit operators', for\nexample).\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"CardholderCompetency":{"title":"Cardholder competency","description":"A _competency_ is an object in Command Centre with some basic fields like a name and a notice\nperiod.  Its purpose is to allow a site to refuse access to cardholders who do not meet a\nspecial requirement.\n\nThis section describes the link between a cardholder and a competency.  The status of that link\ndetermines whether they \"hold\" the competency for the purposes of access control decisions at\nthe door.  When we talk about updating, adding, or deleting a competency in the cardholder\nAPI, we do not mean the competency object itself, but rather the link a cardholder has to the\ncompetency.\n\nThe link between cardholder and competency is a block in the cardholder detail.  You can\nalso request the server to add it to the results of a cardholder search by putting\n`competencies` in the `fields` parameter.\n\nWhen updating a cardholder's holding of a competency, the fields you send are slightly\ndifferent from what you receive from a cardholder GET:  you do not send read-only blocks\nsuch as `status` and `competency`, and there is a write-only field `enabled` that you can\nsupply to change the status.\n\nYou cannot use a PATCH to move the status, times, comment, and credit to a different\ncompetency.  If you need to do that, delete the cardholder's existing competency and give\nthem a new one.  You can do that in one PATCH.\n\nA cardholder can have only one link to a given competency.  Attempting to give a cardholder\na competency a second time will either fail or raise a stateful alarm and succeed, depending\non your version of Command Centre.\n","type":"object","properties":{"href":{"type":"string","description":"This is the URL of the cardholder's connection to a competency, not the URL of the\ncompetency itself.  Use it as the target of a DELETE to remove a cardholder's\ncompetency, or in the body of a cardholder PATCH to modify it.\n\nDELETE is the only verb you can use on this URL.  GET will return a 404.\n","format":"uri-reference","readOnly":true},"competency":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}},"description":"This contains the competency's name and its href.\n\nAs ever, do not bother putting `name` in the body of a POST or PATCH.  The server will\nignore it.\n"},"status":{"type":"object","properties":{"value":{"type":"string"},"type":{"type":"string"}},"description":"This object contains two strings.  Both are read-only, so do not specify them when\nassigning or updating a cardholder's competency.  `value` is taken from the site's\nlanguage pack, suitable for display. `type` comes from a fixed enumeration.  It will be\n`expiryDue` or `active` when the cardholder carries this competency; anything else means\nno.  A fuller explanation follows.\n\nA competency can be disabled, expired, both, or neither.  Whether it is _enabled_ is a\nflag on the cardholder's holding of the competency.  Whether it is _expired_ is derived from an expiry\ntimestamp (accurate to the second):  if it is in the past, Command Centre considers the\ncompetency expired.\n\nA competency can also have an `enablement` date.  If that date (timestamp) passes while the\ncompetency is disabled, Command Centre will enable the competency.  It will leave the date on\nthe item for future reference, though it will not affect the competency again.\n\nIf the competency is disabled, the status `type` will be `inactive` when there is no\nenable date or it is in the past, and `pending` when the enable date is in the future\n(i.e., there is an automatic re-enablement coming).\n\nIf the competency is not disabled, the `expiry` time is important.  If it is in the past,\n`type` will be `expired`.\n\nAll of those cases are negative.  Two remain, when our cardholder is blessed with an\nenabled and active competency.  `type` will be `expiryDue` if the `expires` time is in the\nfuture but within the competency's advance notice period, or `active` if the `expires`\ntime is beyond the advance notice period or not set at all.\n\nYou can see and set the enabled flag, the enable date, and the expiry date via this\nAPI.\n\nWhen creating a cardholder or updating a competency on an existing cardholder, you should\nset the `enabled` field one way or the other, and the `enablement` and `expiry` dates if\nyou wish.  They will determine the contents of this status block.\n\nHere it is in table form.  The first two rows are the positive cases, when Command Centre\nwould grant access to a competency-enforced zone.\n\n| Enabled flag | Enablement date | Expiry date | `status.type`\n| ------------ | -------------- | --------| ----- |\n| true | - | Far future | active |\n| true | - | Near future | expiryDue |\n| true | - | Past | expired |\n| false | Future | - | pending |\n| false | Past | - | inactive |\n| false | Unset | - | inactive |\n","readOnly":true},"disabled":{"type":"boolean","readOnly":true,"deprecated":true,"description":"Do not use this field.  Instead, take the state of a cardholder's competency from\n`status.type`.  This field is misleading on its own:  even when it is true, the\ncompetency might still be inactive.\n"},"enabled":{"type":"boolean","writeOnly":true,"description":"This is a write-only field.  You will not receive it from the GET.  It changes the\ncompetency between enabled (status type `expired`, `expiryDue`, or `active`) and\ndisabled (status type `inactive` or `pending`).  Set it to false in a PATCH if you want\nto disable the competency now, particularly if you are setting a future enablement date.\n"},"expiryWarning":{"type":"string","description":"The time at which the cardholder will (or did) receive a warning about the\ncompetency expiring.  If this time is set and in the past but the competency has\nnot yet expired and is still enabled, the status type will be `expiryDue`.\n","format":"date-time","readOnly":true},"expiry":{"type":"string","description":"The time at which the competency will expire.  If this time is set, in the past, and the\ncompetency is enabled, status type will be `expired`.\n","format":"date-time"},"enablement":{"type":"string","description":"The time at which the competency will be re-enabled.  If set and in the future, and the\ncompetency is disabled, the status type will be `pending`.\n\nYou can set this on an enabled competency but it has no effect there, so with this field\nyou would generally also set `enabled: false`.\n","format":"date-time"},"comment":{"type":"string","description":"The comment appears in the management clients when viewing the cardholder.\n"},"limitedCredit":{"type":"boolean","description":"If false, Command Centre's 'Pre-pay Car Parking' feature (available under its own licence)\nwill not reduce the current credit.\n\nThis field will be in the results if its value is true.\n"},"credit":{"type":"integer","description":"The balance, or amount of credit left on this competency for use by Pre-pay Car Parking.\nIt can be negative.\n\nThis field will be in the results if its value is not zero.\n"}}},"CardholderRelationship":{"title":"Cardholder relationship","description":"A _role_ is an object in Command Centre.  Roles are usually named using nouns such as\n'supervisor', 'manager', or 'team leader'.\n\nThe operator clients and the REST API allow you to create a link between two\ncardholders, called a relationship, using a role.  The link is directional:  we\nrefer to the cardholder who 'has' the role as the child, and the cardholder who\nperforms or 'is' the role as the parent.\n\nA parent can perform a role for any number of child cardholders, but a child can only have one\nrelationship (parent) for each role.  Command Centre will reject your submission if you try to\ncreate a relationship when one already exists for the same child and role.\n\nFor example, a role on your system might be 'supervisor'.  A cardholder can be a supervisor\nfor any number of others, but will only have one supervisor.\n\nLoops are possible:  two cardholders can supervise each other.\n\nThe REST API manages relationships through the child cardholder.  You can create them at the\nsame time as creating the child in a POST, or add them later in a PATCH.\n\nThere is currently no way to list all a cardholder's children in one request (everyone a\nparticular cardholder is supervising, for example).  You would achieve that by iterating\nthrough all cardholders, after re-reading the efficiency tips, and checking their\nrelationships - quite easily done in JSONPath.\n\nThis section describes the object you receive in a cardholder's detail page and you will send\nin a POST or PATCH.  The child cardholder does not appear in it because he or she is\nidentified by the URL of the request.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the href of the link between two cardholders.  DELETE it, or put it in\n`relationships.remove.href` of a PATCH directed at the child cardholder, to sever the\nrelationship.  Specify it in `relationships.update.href` of a PATCH to the child\ncardholder to update the relationship.\n\nDo not specify it when creating a new relationship.  The server generates it for you.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"role":{"type":"object","description":"This is the role that the parent identified in the `cardholder` block performs for the\ncardholder identified by the request URL.\n\nOnce set, this cannot be changed.  Command Centre will ignore it if you send it\nin an update PATCH.  If you need to swap a parent from one role to another, send\nan add and a delete in the same PATCH.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"cardholder":{"type":"object","description":"The href and name of the cardholder that performs this role.\n\nThe three name fields are read-only:  Command Centre sends them to you in the body of a\nGET but will ignore them if you send them in the body of a POST or PATCH.\n\nThis block and the href in it are unnecessary when deleting a relationship.  The href is\nrequired when creating one, and optional when updating, but strongly advised since the\ncardholder is the only thing about a relationship you can change.\n\n`firstName` and `lastName` appeared in 8.20.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for the parent cardholder."},"firstName":{"type":"string","readOnly":true},"lastName":{"type":"string","readOnly":true}}}}},"CardholderLocker":{"title":"Cardholder locker","description":"These appear in an array in a cardholder detail, showing the cardholder's allocated lockers.\nEach allocation has `from` and `until` dates, much like cards and access group memberships,\noutside of which the allocation is inactive.\n\nA locker can have allocations to more than one cardholder, with separate or overlapping\nperiods.  Unlike access groups, however, one cardholder cannot have more than one allocation\nto the same locker.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this to end a cardholder's use of a locker, or use it to identify the\nallocation you wish to modify in a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-).\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"locker":{"description":"The href in this object is a link to the allocated locker, and is the identifier to use\nwhen allocating the same locker to another cardholder.\n\nThe object also contains the name and short name of the locker, and the name and\nidentifying href of its bank.\n","type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for a locker."},"shortName":{"type":"string","readOnly":true},"lockerBank":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}},"from":{"description":"The start of the time period during which the cardholder has access to this locker.\n\nSend an empty string `\"\"` to reset it.\n","type":"string","format":"date-time"},"until":{"description":"The end of the time period during which the cardholder has access to this locker.\n\nSend an empty string `\"\"` to reset it, making the allocation permanent.\n","type":"string","format":"date-time"}}},"CardholderElevatorGroup":{"title":"Cardholder elevator group","description":"These appear in an array in a cardholder detail, showing the cardholder's elevator group\nproperties, and can go into the body of a POST or PATCH to set a cardholder's elevator group\nproperties.\n\nA cardholder can have one default floor per elevator group. The elevator system will\nprepare a car to carry that cardholder to the access zone shown here when the cardholder\nbadges a card at an appropriately configured kiosk.\n\nElevator system features can be activated by enabling the feature for an elevator group.\nFor example, 'VIP features' gives exclusive access to an elevator car to the passenger.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"The href of this cardholder's elevator group entry.  DELETE this to remove it from the\ncardholder.\n"},"elevatorGroup":{"type":"object","description":"The href and name of the elevator group for which this cardholder has a default\nfloor or passenger type.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"accessZone":{"type":"object","description":"The href and name of the access zone (floor) to which this cardholder is most\nlikely to want to travel after entering the group's main elevator lobby. This \nproperty will be missing if the cardholder does not have a default floor for this elevator group.\n","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"enableCaptureFeatures":{"type":"boolean","description":"Cardholders can select and recall specific elevators to specific floors using\na kiosk. Once captured, the elevator car can be placed on independent service to\ngive users control of the car to clean the interior or perform maintenance.\n"},"enableCodeBlueFeatures":{"type":"boolean","description":"A special elevator mode which is commonly found in hospitals. It allows an elevator\nto be summoned to any floor for use in an emergency situation.\n"},"enableExpressFeatures":{"type":"boolean","description":"Allows the cardholder to program selected elevators to cycle continuously between two\nfloors for a pre-determined duration. For example, this feature can help hotels transport\nfood efficiently from their kitchen to a ballroom on another floor. You can also prevent\nother guests from boarding to provide your banquet guests with VIP treatment.\n"},"enableServiceFeatures":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop\nto their destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableService2Features":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop\nto their destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableService3Features":{"type":"boolean","description":"Service personnel can use this function to call an empty elevator and ride it nonstop to\ntheir destination floor. The user simply registers a call via a card swipe or PIN entry\nthat is pre-programmed to grant access.\n"},"enableVipFeatures":{"type":"boolean","description":"VIP operation allows cardholders to swipe a card or enter a PIN to isolate the elevator\nand provide uninterrupted access to their designated floor.\n"}}}}}}
```

## The CardholderPATCH object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderPATCH":{"title":"Cardholder PATCH","description":"Send one of these in a PATCH to `/api/cardholders/{id}` to modify the cardholder at that\nURL, or to add and modify cards, competencies, personal data, group memberships, and\nrelationships.\n\nThis model only shows some of the fields available on a cardholder.  The full list is in\nthe [cardholder detail](models#cardholderdetail).\n","properties":{"authorised":{"type":"boolean"},"firstName":{"type":"string"},"@employeeId":{"type":"string","description":"Replace PDF values as though they were flat fields on a cardholder.  Prefix the name of\nthe PDF with `@`, and Base64-encode images.  Send 'null' if you want to delete a PDF value.\n\nRemember that a cardholder's record will not return a PDF if they are not a member of an\naccess group that grants that PDF.  Current versions of Command Centre are tolerant of\nyour attempts to change the PDF in that situation, but future versions may not be.\n"},"personalDataDefinitions":{"description":"This is how you set and unset the notifications flags on PDFs.\n","type":"array","items":{"$ref":"#/components/schemas/CardholderPDF"}},"cards":{"type":"object","description":"This object can contain three arrays, named `add`, `update`, and `remove`.  Every element\nyou put in those arrays should be in the [card schema](models#cardholdercard).\n\nEach element of the `add` array will need a `type` member, at the very least.  Every\ncard field makes sense here except `href`.  Only existing cards have hrefs.  This\nexample adds two cards:  one has nothing more than the type, so it will receive the card\ntype's default validity dates, if any, and a computed number and issue level.  The other\nis a mobile credential (it has an `invitation` block) with a custom initial state.\n\nEach element of the `update` array should be a card to modify.  It will need the href of\nthat card, plus the fields you want to change.  Remember you cannot change a card's type.\nThe example changes the issue level and resets the `until` date.\n\nThe only fields that make sense in an element of the `remove` array are `href` and `status`.\n\nYou can remove and add cards in the same PATCH.  In fact you should do that in preference\nto making multiple API calls.  That is a good way of reissuing a mobile credential, for\nexample:  put the href to the old one in the `remove` array and a new invitation in the\n`add` array.  The new credential should have the same card number and the same `type` and\n`invitation` blocks as the credential you're re-issuing.\n\nDo not put the same href in both the `update` and `remove` arrays.\n\nIn version 8.90 and later you can specify a card state in the `value` field inside the\n`status` block when removing a card or changing its issue level.  It becomes the final\nstate of the card if you remove it or the final state of the card with the previous issue\nlevel if you re-issue it, so it must be one of the valid states for the card type.  The\nGallagher clients and the resulting event call this state the 'reason' for the re-issue or\nremoval.  By default it will be the same as the card's current state.\n"},"accessGroups":{"type":"object","description":"Like the `cards` object, this can contain three arrays named `add`, `update`, and\n`remove`.  Every element you send in those arrays should be in the [access group\nschema](models#cardholderaccessgroup).\n\nThis operation does not modify access groups in Command Centre; it works on a cardholder's\nmemberships to those groups.\n\nEach element of the `add` array will need an `accessGroup` member containing an href\nidentifying the group to which you wish to add the cardholder.  The other fields are\noptional.  If you omit `from`, the membership will take effect immediately.  If you omit\n`until`, it will be unending.\n\nEach element of the `update` array will need an href identifying the membership (not the group!) to update,\nand one or both of the `from` and `until` date-times with new values.  You cannot\nchange the group:  just the activity period.  The example removes the until date, effectively making\nthe group membership unending.\n\nIn version 7.90.883 or earlier, `from` and `until` should be in UTC with a\ntrailing 'Z'.  Releases after 883 understand different timezones here.\n\nNote that updating a cardholder's group membership will change its href, so do not cache\nit.\n\nThe only field that makes sense in an element of the `remove` array is the href.\n\nDo not put the same href in both the `update` and `remove` arrays.\n"},"competencies":{"type":"object","description":"Like the cards and accessGroups objects, this can contain three arrays named `add`,\n`update`, and `remove`.  Every element should be in the [cardholder competency\nschema](models#cardholdercompetency).\n\nThis operation does not modify Command Centre's competencies:  it works on a cardholder's\nholdings of those competencies.\n\nEach element of the `add` array will need a `competency` block containing an href member\nidentifying the competency you wish to grant the cardholder.  All other fields are optional.\nNote that attempting to give a cardholder a competency he or she already has\nwill result in an error or an alarm depending on the server version.\n\nEach element of the `update` array will need an href identifying the\ncardholder/competency link to update, and one or more of the `expiry`, `enabled`,\n`enablement`, `comment`, `limitedCredit`, and `credit` fields.\n\nThe only field that makes sense in an element of the `remove` array is the href\nof the link between the cardholder and the competency.\n\nDo not put the same href in both the `update` and `remove` arrays.\n\nIn this example we are giving the cardholder a disabled competency which will enable\nin 2021, and activating another competency.\n"},"relationships":{"type":"object","description":"It should be no surprise that this can contain three arrays named `add`, `update`, and\n`remove`, and that every element should be in the [relationship\nschema](models#cardholderrelationship).\n\nThis operation does not modify Command Centre's roles:  it works on the relationships\nbetween two cardholders.\n\nEach element of the `add` array will need a `role` member containing an href identifying\nthe type of relationship you wish to establish, and a `cardholder` member containing an\nhref identifying the other party (the one who will perform the role for the cardholder at\nthe URL you are PATCHing).  There are no optional fields.\n\nEach element of the `update` array will need an href identifying the relationship to\nupdate, and one or both of the `role` and `cardholder` blocks containing the updated\nvalues.  The example leaves the role but changes the cardholder - a new supervisor,\npresumably.\n\nThe only field that makes sense in an element of the `remove` array is the href.\n\nDo not put the same href in both the `update` and `remove` arrays.\n"},"lockers":{"type":"object","description":"With you well in the habit by now, each element of your three arrays should be in the\n[cardholder locker schema](models#cardholderlocker).  They will allocate lockers to\ncardholders, de-allocate them, and adjust validity periods.\n\nEach member of the `add` array will need a `locker` member containing an href identifying\nthe locker to allocate.  The cardholder you will allocate it to is identified by the\nrequest URL, remember.\n\nEach member of the `update` array will need an href identifying the allocation to update,\nand one or both of the `from` and `until` date-times.\n\nThe validity period is all you can change about a locker allocation.  If you want to\nchange the locker, delete the old one and add another.  You can do that in the same PATCH,\nwith one element in each of the `remove` and `add` arrays.\n\nThis example allocates one locker starting in January 2019, sets the end-date of an\nexisting allocation to the end of February 2020, and removes another entirely.\n"},"operatorGroups":{"type":"object","description":"This can contain two arrays named `add` and `remove`.  Every element you send in those\narrays should be in the [cardholder operator group\nschema](models#cardholderoperatorgroup).\n\nEach element of the `add` array will need an `operatorGroup` member containing an href\nidentifying the operator group to which you wish to add the cardholder.  Supported in 8.50\nand later.\n\nThe only field that makes sense in an element of the `remove` array is the href.  Make\nsure it is the href of the membership, not of the operator group.  Supported in 8.90 and\nlater.\n\nThere is nothing about an operator group membership that you can change so there is no\npoint to an `update` array.  Operator group memberships are, or are not:  there is no\nupdate.\n"},"elevatorGroups":{"type":"object","description":"This can contain three arrays named `add`, `update`, and\n`remove`, each containing an element in the [cardholder elevator group\nschema](models#cardholderelevatorgroup).\n\nThe `elevatorGroup` block only makes sense in the `add` array.  The `update` array is for\nchanging the cardholder's default floor and passenger types on an existing elevator group\nassignment.\n\nThe server will ignore all fields in the elevatorGroup and accessZone objects except `href`\nif you place them in the body of your PATCH.\n\nRemove the default floor in an update by supplying an accessZone block with the href set\nto null or \"\".\n\nChange a passenger type in an update by supplying the new value. The passenger type will\nbe unchanged otherwise.\n\nAs with cards and access group memberships etc., the server ignores root-level hrefs in\nthe elements of an `add` array, requires them in the `update` array (since they indicate\nthe entries to work on), and ignores everything but them in the `remove` array.\n\nThe example shows our cardholder receiving a default floor for one elevator group and\nupdating the Code Blue and VIP passenger types for another elevator group.\n\nAdded in 8.50.\n"}}},"CardholderPDF":{"title":"Cardholder PDF","description":"A personal data definition and its value for a cardholder.  Each definition is an object\ncontaining one property named after the PDF (plus a leading '@'), which in turn contains its\nvalue and notifications flag for the containing cardholder and an object containing some of\nthe PDF definition's basic fields.\n\nThis is returned as part of a [cardholder](models#cardholderdetail), and you can send it\nin a [POST](models#cardholderpost) or a\n[PATCH](models#cardholderpatch) to set the PDF's value and notification flag for\na cardholder.  The server will ignore the `definition` block if you send it back.  It uses the\nname of the block (minus its leading `@`) to find the PDF to change.\n\nWhile you can use this structure to change the value of a cardholder's PDF, it may be simpler\nto put a property in the root of the payload named after the PDF with a leading '@'.\n","type":"object","additionalProperties":{"$ref":"#/components/schemas/CardholderPDFContent"}},"CardholderPDFContent":{"title":"Cardholder PDF content","type":"object","properties":{"href":{"type":"string","description":"GET this link to receive this cardholder's value for this PDF.  If it is an image you will\nreceive the raw image data with an appropriate content-type.  A browser will render it\ncorrectly.\n\nIf the PDF is not an image the content type will be text/plain, encoded (like\neverything else in this API) as UTF-8.  But you should only use it for image PDFs\nbecause:\n\n* Values for scalar PDF types (everything except images) are also given to you in the\n  `value` field in this object, described below.\n\n* The format of date PDFs varies with the Command Centre version.  Old servers return\n  it in a format that depends on the server's locale.  This was a bug.  Newer servers\n  use ISO 8601.\n\n* If you learn this URL while a cardholder has the PDF, then the cardholder loses\n  it, then you GET the URL, results will vary depending on the server version.  The\n  correct result is a 404, and if the PDF is an image or the server is recent you\n  will see that.  But old servers may return a blank string or even a 500 for\n  non-image PDFs.\n\nThis field will be absent if the cardholder does not have a value for the PDF.\n\nIt is read-only:  do not send it in a PATCH or POST.\n","format":"uri-reference","readOnly":true},"definition":{"type":"object","properties":{"href":{"type":"string","description":"This is the href of the PDF's definition, common to all cardholders who hold a value\nfor this PDF.\n","format":"uri-reference"},"name":{"type":"string","description":"The PDF's name, without an '@' prefix.\n"},"id":{"type":"string","description":"Short alphanumeric identifier used elsewhere in the API to filter cardholder searches\nand add PDF values to alarm and event GETs.\n"},"type":{"type":"string","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]}},"description":"The definition object is read-only:  do not send it in a PATCH or POST.\n","readOnly":true},"value":{"description":"In a GET response for text, numeric, and date PDFs this will be a scalar containing the\nvalue, but for image PDFs it will be an object containing a copy of the `href` field\nabove.  For date PDFs the string will comply with RFC 3339, but may or may not contain a\ntime depending on the version of Command Centre.  Newer versions omit the `T` separator\nand everything after it.  If there, it will be midnight UTC.\n\nIn versions up to and including 8.60, if a cardholder did not have an image PDF captured\n(in other words they were a member of an access group that included an image PDF, but they\ndid not have a value for it) the API returned the string 'Not captured' in the `value`\nfield.  Versions 8.70 and later will not return the `value` field at all if there is no image.\n\nIn a POST or PATCH send text PDFs (including dates) as strings, numeric PDFs as numbers or\nstrings that parse to numbers, and image data Base64-encoded into a string.\n","oneOf":[{"type":"integer","title":"Numeric","description":"The scalar value of the numeric PDF."},{"type":"string","title":"Text or date","description":"The scalar value of the text or date PDF."},{"type":"object","title":"Image","description":"An object containing an href which, when requested from the server, returns the\nimage PDF.  The server does not transcode images:  it will arrive as the same\ncontent type as uploaded.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"Only present for image PDFs, this will be a copy of the href field in the parent\nobject.  When requested from the server it will return the image PDF as it was\nuploaded.\n"}}}]},"notifications":{"type":"boolean","description":"In a GET response, this will only appear for email and mobile PDF types.  In a POST or\nPATCH, it only makes sense for the same types.\n\nIf true, cardholder notifications will go to the telephone number or email address held by\nthis PDF.  Cardholders can have their notifications go to as many contacts as they wish.\n"}}}}}}
```

## The CardholderChange object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderChange":{"title":"Cardholder change","description":"`/api/cardholders/changes` returns an array of these.  Each contains a description of a change\nmade to a cardholder.\n\nIn this example a cardholder has had his name changed from Craig to Gavin, has had an\nenablement date set on a competency, and has had a card and access group membership added.\n\n## Notes\n\n- Changes to an access group membership will have a different href in the `oldValues` and\n  `newValues` blocks, because modifying a group membership changes its ID.\n\n- The API will not notify changes to a competency's `credit` integer or `limitedCredit`\n  boolean.  These fields are part of a separate Command Centre feature and are not supported\n  by the changes API.\n\n- The API will report a spurious change to a PDF value when a cardholder rejoins an access\n  group he or she was previously a member of, provided that access group carried a PDF with no\n  default and the cardholder did not have a value for it.\n\n- This API will not notify changes to `lastSuccessfulAccessTime` or\n  `lastSuccessfulAccessZone`.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Command Centre's identifier for this change.  This has no use in the API:  you cannot use\nit as a URL, but you may like to use it to track the changes you have seen.\n"},"time":{"type":"string","format":"date-time","description":"The time that this change occurred."},"type":{"description":"`add` if this change added a cardholder, `update` if it modified a cardholder, or `remove`\nif it deleted a cardholder.\n","type":"string","enum":["add","update","remove"]},"item":{"description":"A block containing the href of the changed cardholder.  You can GET this URL to find the\ncardholder's current state, or you could add the cardholder block to the change using\n`fields=cardholder` in the query.  Note that you can add individual cardholder fields such\nas PDFs using `fields=defaults,cardholder.personalDataFields`.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"operator":{"description":"A block containing the href and current name of the operator who made this change.\n\nBecause building this block requires more work from the server it is not in the default\nfield set.  If you need it you must ask for it using the fields parameter:\n`fields=defaults,operator`.\n","type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"oldValues":{"type":"object","description":"A block containing the values of the changed fields before the change, if Command Centre\nstill has them, in the same format as a [cardholder\ndetail](models#cardholderdetail).  If a value is blank, it means that the value was\nnull before the change or the server no longer has it.\n\nBecause this requires extra effort from the server, you may like to omit this block using\nsomething like `fields=time,type,item,operator` unless you are particularly interested in\nhistorical data.\n"},"newValues":{"type":"object","description":"A similar block containing the values of the changed fields after the change, if the\nserver has them.\n\nGenerally, this block is less useful than the current state of the cardholder, described\nnext.  It also requires extra effort from the server, so you may like to omit this block\nusing `fields`.\n"},"cardholder":{"description":"A block containing the current fields on the cardholder, provided the cardholder has not\nbeen deleted.  This is in the same format as a [cardholder\ndetail](models#cardholderdetail).\n\nBecause building this requires more work from the server it is not in the default result\nset.  If you need it you must ask for it using the `fields` parameter.  While the server\nhas a default field set for cardholders, your query will be more efficient if you ask for\njust the fields you need:\n`fields=defaults,cardholder.firstName,cardholder.lastName,cardholder.cards`, etc.  Note\nhow you must prefix each field with `cardholder` since they are all inside a block with\nthat name.\n","type":"object"}}}}}}
```

## The CardTypeSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardTypeSearch":{"title":"Card type search","description":"An array of card types, and a `next` link for more.  Sites generally have only a handful of\ncard types, so when retrieving them you should set your 'top' parameter high enough that you\ndo not need the 'next' link.\n\nFor the same reason, the default set of fields is much larger than it is for other items.\n","properties":{"results":{"type":"array","description":"An array of card types.","items":{"$ref":"#/components/schemas/CardType"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"CardType":{"title":"Card type","description":"This object describes a single Card Type.  \"Credential type\" would be a better name, as\nCommand Centre's card types include credentials that do not require a plastic card.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"This is the identifier to use when assigning a card to a cardholder in a cardholder\n[PATCH](cardholders#patch-api-cardholders-id-) or\n[POST](cardholders#post-api-cardholders-id-).\n\nThis is also the URL for the card type's detail page.  GETting it will return you a 404 if\nyou do not have 'View site' or 'Configure site' on the card type's division."},"id":{"type":"string","readOnly":true,"description":"The API does not use this field.  Nor should you.\n"},"name":{"type":"string","description":"It is best if this is descriptive, so that operators are more likely to assign people\nthe intended kind of credential.\n"},"description":{"type":"string","description":"Like the name, this helps operators distinguish different card types.\n"},"division":{"type":"object","description":"The division that contains this card type.  Required when creating a card type.\n"},"notes":{"type":"string","description":"Free text.\n\nBecause of its potential size, the server does not return the notes field by default.  You\nneed to ask for it with `fields=notes`.\n"},"facilityCode":{"type":"string","description":"A facility code is a letter (A-P) followed by up to five digits.  It is encoded onto cards\nso that they only work at sites with the correct facility code.\n\nPIV cards, PIV-I cards, and mobile credentials do not have a facility code.\n\nMost credential classes require a facility code on creation.  But it cannot be changed\nonce set, so this field is ignored in a PATCH.\n"},"availableCardStates":{"readOnly":true,"type":"array","items":{"type":"string","enum":["Active","Disabled (manually)","Lost","Stolen","Damaged"]},"description":"All credential types have a set of card states.\n\nIf you need this, ask for it using the `fields` parameter.\n\nThis field is read-only:  it is derived from the card type's card state set (also known as\na workflow).  If you send it in a POST or a PATCH, the server will ignore it.\n"},"credentialClass":{"type":"string","description":"Required when creating a new card type but ignored when modifying one since a credential's\ntype cannot be changed once set.\n","enum":["card","mobile"]},"minimumNumber":{"description":"For card types with decimal card numbers, this is the minimum.  Must be non-negative.\n","type":"integer","default":1},"maximumNumber":{"description":"For card types with decimal card numbers, this is the maximum.  Must be non-negative.\n\nThe default depends on the credential type.  It is 16,777,215 (24 bits) for regular cards.\n","type":"integer"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"regex":{"description":"This is the regular expression that a text card number\nmust match before Command Centre will accept it. \n","type":"string"},"regexDescription":{"description":"Regular expressions often need explaining to your users.  Do it here.","type":"string"},"cardStateSet":{"description":"A block containing the href to the card type's card state set.  Required when creating a new card type.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"defaultIssueLevel":{"type":"integer","default":1,"description":"The value copied to a new credential of this type when created without an issue level."},"cardIssueLevelMustMatchDefault":{"type":"boolean","default":false,"description":"If true, Command Centre will prevent operators setting the issue level on cards of this\ntype to any value other than the default.\n\nWhen PATCHing a card type, attempting to set this true will fail if there are any\nexisting cards of the type with issue levels different from the default.\n"},"enableExpiryNotifications":{"type":"boolean","default":true,"description":"Whether a card expiration should generate a notification."},"warningPeriod":{"type":"integer","minimum":0,"default":0,"description":"Command Centre can send out notifications when a credential is due to expire this period\nin the future.\n\nIts units are set by `warningPeriodType`.\n\nA value of zero means the card type does not support notifications.\n"},"warningPeriodType":{"type":"string","default":"days","enum":["noperiod","days","weeks","months","years"],"description":"This sets the units for `warningPeriod`.\n\nIt will contain the value `noperiod` if the card type does not support expiry notifications.\n"},"minimumPinLength":{"type":"integer","default":4,"description":"The length of PINs on credentials of this type."},"inactivityTimeoutInDays":{"type":"integer","default":30,"description":"This is the period, in days, after which Command Centre will consider a credential of this type\nto be inactive.\n\nIt only comes out in a GET if the card type disables inactive cards.\n"},"allowReprint":{"type":"boolean","default":false,"description":"This indicates whether Command Centre clients should allow printing of a credential of this type.  It\nusually only applies to physical card types.\n"},"allowReEncode":{"type":"boolean","default":false,"description":"This shows whether Command Centre clients should allow re-encoding of a credential of\nthis type.  It usually only applies to physical card types.\n"},"sendRegistrationEmail":{"type":"boolean","description":"Only relevant for Gallagher mobile credentials.  If true, Command Centre will send an\nemail invitation to provision a new credential.  If false, the integration that creates\ncredentials of this type must do that.\n"},"sendRegistrationSms":{"type":"boolean","description":"Only relevant for Gallagher mobile credentials.  If true, Command Centre will send an\nSMS invitation to provision a new credential.  If false, the integration that creates\ncredentials of this type must do that.\n"},"cardNumberFormat":{"type":"string","enum":["decimal","text","hex"],"default":"decimal","description":"Required for credentials of credential class `card`.\n\nPOST only.  You cannot change this on an existing card type.\n"},"defaultExpiry":{"type":"object","readOnly":true,"description":"A block containing duplicates of the following fields that describe the rules for\nexpiring inactive cards.  They have the same names with the leading 'default' removed.\n\nThis block is read-only.  You can request it in a GET, but the server will ignore it if\nyou send it in a POST or PATCH.  It is probably better to pretend it does not exist and\nuse `defaultExpiryType`, `defaultExpiryFrom`, `defaultExpiryUntil`, and\n`defaultExpiryDuration`.\n"},"defaultExpiryType":{"type":"string","enum":["explicitDateTime","duration"],"description":"`explicitDateTime` means that cards of this type created without an activity period will\ninherit it from here.  One or both of the `from` and `until` dates can be missing.\n\n`duration` means that cards of this type created without activity start and end dates\nwill receive a blank `from` date, so they will be active immediately, and an `until`\ndate `defaultExpiryDuration` days in the future.\n"},"defaultExpiryFrom":{"type":"string","format":"date-time","description":"The value copied to a new credential of this type when created without it.  Only useful\nif `defaultExpiryType` is `explicitDateTime`.\n"},"defaultExpiryUntil":{"type":"string","format":"date-time","description":"The value copied to a new credential of this type when created without it.  Only useful\nif `defaultExpiryType` is `explicitDateTime`.\n"},"defaultExpiryDuration":{"type":"string","description":"Used when `defaultExpiryType` is `duration` and a credential of this type is created\nwithout an activity period.  Its start date is left clear, meaning \"now\", and its end\ndate is set `defaultExpiryDuration` into the future.\n\nThis is an ISO 8601 duration, so it will be of the form 'PnYnMnWnDTnHnM'.  Such\ndurations always start with a 'P'.  'n' is a number, and the 'Y', 'M', 'W', 'D', 'H',\nand 'M' following them are for years, months, weeks, days, hours, and minutes.  The 'T'\nis there if the units of the duration are smaller than a day, to distinguish months and\nminutes.  If any 'n' is zero then it and the unit character following it will be\nmissing.\n\nSince card lifetimes can only have one unit, the string will always be one of `PnY`,\n`PnM`, `PnW`, `PnD`, `PTnH`, or `PTnM`.\n\nFor example, if you set `defaultExpiryType=\"duration\"` and `defaultExpiryDuration=\"P7D\"`\nall cards of this type created without a `from` and `until` date of their own will be\ngood for one week.\n\nNot sent by the server unless the expiry type is `duration`.\n"}}}}}}
```

## The CardType object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardType":{"title":"Card type","description":"This object describes a single Card Type.  \"Credential type\" would be a better name, as\nCommand Centre's card types include credentials that do not require a plastic card.\n","properties":{"href":{"type":"string","format":"uri-reference","readOnly":true,"description":"This is the identifier to use when assigning a card to a cardholder in a cardholder\n[PATCH](cardholders#patch-api-cardholders-id-) or\n[POST](cardholders#post-api-cardholders-id-).\n\nThis is also the URL for the card type's detail page.  GETting it will return you a 404 if\nyou do not have 'View site' or 'Configure site' on the card type's division."},"id":{"type":"string","readOnly":true,"description":"The API does not use this field.  Nor should you.\n"},"name":{"type":"string","description":"It is best if this is descriptive, so that operators are more likely to assign people\nthe intended kind of credential.\n"},"description":{"type":"string","description":"Like the name, this helps operators distinguish different card types.\n"},"division":{"type":"object","description":"The division that contains this card type.  Required when creating a card type.\n"},"notes":{"type":"string","description":"Free text.\n\nBecause of its potential size, the server does not return the notes field by default.  You\nneed to ask for it with `fields=notes`.\n"},"facilityCode":{"type":"string","description":"A facility code is a letter (A-P) followed by up to five digits.  It is encoded onto cards\nso that they only work at sites with the correct facility code.\n\nPIV cards, PIV-I cards, and mobile credentials do not have a facility code.\n\nMost credential classes require a facility code on creation.  But it cannot be changed\nonce set, so this field is ignored in a PATCH.\n"},"availableCardStates":{"readOnly":true,"type":"array","items":{"type":"string","enum":["Active","Disabled (manually)","Lost","Stolen","Damaged"]},"description":"All credential types have a set of card states.\n\nIf you need this, ask for it using the `fields` parameter.\n\nThis field is read-only:  it is derived from the card type's card state set (also known as\na workflow).  If you send it in a POST or a PATCH, the server will ignore it.\n"},"credentialClass":{"type":"string","description":"Required when creating a new card type but ignored when modifying one since a credential's\ntype cannot be changed once set.\n","enum":["card","mobile"]},"minimumNumber":{"description":"For card types with decimal card numbers, this is the minimum.  Must be non-negative.\n","type":"integer","default":1},"maximumNumber":{"description":"For card types with decimal card numbers, this is the maximum.  Must be non-negative.\n\nThe default depends on the credential type.  It is 16,777,215 (24 bits) for regular cards.\n","type":"integer"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"regex":{"description":"This is the regular expression that a text card number\nmust match before Command Centre will accept it. \n","type":"string"},"regexDescription":{"description":"Regular expressions often need explaining to your users.  Do it here.","type":"string"},"cardStateSet":{"description":"A block containing the href to the card type's card state set.  Required when creating a new card type.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"defaultIssueLevel":{"type":"integer","default":1,"description":"The value copied to a new credential of this type when created without an issue level."},"cardIssueLevelMustMatchDefault":{"type":"boolean","default":false,"description":"If true, Command Centre will prevent operators setting the issue level on cards of this\ntype to any value other than the default.\n\nWhen PATCHing a card type, attempting to set this true will fail if there are any\nexisting cards of the type with issue levels different from the default.\n"},"enableExpiryNotifications":{"type":"boolean","default":true,"description":"Whether a card expiration should generate a notification."},"warningPeriod":{"type":"integer","minimum":0,"default":0,"description":"Command Centre can send out notifications when a credential is due to expire this period\nin the future.\n\nIts units are set by `warningPeriodType`.\n\nA value of zero means the card type does not support notifications.\n"},"warningPeriodType":{"type":"string","default":"days","enum":["noperiod","days","weeks","months","years"],"description":"This sets the units for `warningPeriod`.\n\nIt will contain the value `noperiod` if the card type does not support expiry notifications.\n"},"minimumPinLength":{"type":"integer","default":4,"description":"The length of PINs on credentials of this type."},"inactivityTimeoutInDays":{"type":"integer","default":30,"description":"This is the period, in days, after which Command Centre will consider a credential of this type\nto be inactive.\n\nIt only comes out in a GET if the card type disables inactive cards.\n"},"allowReprint":{"type":"boolean","default":false,"description":"This indicates whether Command Centre clients should allow printing of a credential of this type.  It\nusually only applies to physical card types.\n"},"allowReEncode":{"type":"boolean","default":false,"description":"This shows whether Command Centre clients should allow re-encoding of a credential of\nthis type.  It usually only applies to physical card types.\n"},"sendRegistrationEmail":{"type":"boolean","description":"Only relevant for Gallagher mobile credentials.  If true, Command Centre will send an\nemail invitation to provision a new credential.  If false, the integration that creates\ncredentials of this type must do that.\n"},"sendRegistrationSms":{"type":"boolean","description":"Only relevant for Gallagher mobile credentials.  If true, Command Centre will send an\nSMS invitation to provision a new credential.  If false, the integration that creates\ncredentials of this type must do that.\n"},"cardNumberFormat":{"type":"string","enum":["decimal","text","hex"],"default":"decimal","description":"Required for credentials of credential class `card`.\n\nPOST only.  You cannot change this on an existing card type.\n"},"defaultExpiry":{"type":"object","readOnly":true,"description":"A block containing duplicates of the following fields that describe the rules for\nexpiring inactive cards.  They have the same names with the leading 'default' removed.\n\nThis block is read-only.  You can request it in a GET, but the server will ignore it if\nyou send it in a POST or PATCH.  It is probably better to pretend it does not exist and\nuse `defaultExpiryType`, `defaultExpiryFrom`, `defaultExpiryUntil`, and\n`defaultExpiryDuration`.\n"},"defaultExpiryType":{"type":"string","enum":["explicitDateTime","duration"],"description":"`explicitDateTime` means that cards of this type created without an activity period will\ninherit it from here.  One or both of the `from` and `until` dates can be missing.\n\n`duration` means that cards of this type created without activity start and end dates\nwill receive a blank `from` date, so they will be active immediately, and an `until`\ndate `defaultExpiryDuration` days in the future.\n"},"defaultExpiryFrom":{"type":"string","format":"date-time","description":"The value copied to a new credential of this type when created without it.  Only useful\nif `defaultExpiryType` is `explicitDateTime`.\n"},"defaultExpiryUntil":{"type":"string","format":"date-time","description":"The value copied to a new credential of this type when created without it.  Only useful\nif `defaultExpiryType` is `explicitDateTime`.\n"},"defaultExpiryDuration":{"type":"string","description":"Used when `defaultExpiryType` is `duration` and a credential of this type is created\nwithout an activity period.  Its start date is left clear, meaning \"now\", and its end\ndate is set `defaultExpiryDuration` into the future.\n\nThis is an ISO 8601 duration, so it will be of the form 'PnYnMnWnDTnHnM'.  Such\ndurations always start with a 'P'.  'n' is a number, and the 'Y', 'M', 'W', 'D', 'H',\nand 'M' following them are for years, months, weeks, days, hours, and minutes.  The 'T'\nis there if the units of the duration are smaller than a day, to distinguish months and\nminutes.  If any 'n' is zero then it and the unit character following it will be\nmissing.\n\nSince card lifetimes can only have one unit, the string will always be one of `PnY`,\n`PnM`, `PnW`, `PnD`, `PTnH`, or `PTnM`.\n\nFor example, if you set `defaultExpiryType=\"duration\"` and `defaultExpiryDuration=\"P7D\"`\nall cards of this type created without a `from` and `until` date of their own will be\ngood for one week.\n\nNot sent by the server unless the expiry type is `duration`.\n"}}}}}}
```

## The CompetencySearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CompetencySearch":{"title":"Competency search","description":"An array of competency summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of competency summaries.","items":{"$ref":"#/components/schemas/CompetencySummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"CompetencySummary":{"title":"Competency summary","description":"The competency search at `/api/competencies` returns an array of these.  The object contains\nsome of what you get from a competency's detail page at `/api/competencies/{id}`, linked as\nthe href in this object.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the identifier to use when assigning a competency to a cardholder in a\n[PATCH](cardholders#patch-api-cardholders-id-) or\n[POST](cardholders#post-api-cardholders-id-)."},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"serverDisplayName":{"type":"string"},"notes":{"type":"string"}}}}}}
```

## The CompetencySummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CompetencySummary":{"title":"Competency summary","description":"The competency search at `/api/competencies` returns an array of these.  The object contains\nsome of what you get from a competency's detail page at `/api/competencies/{id}`, linked as\nthe href in this object.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the identifier to use when assigning a competency to a cardholder in a\n[PATCH](cardholders#patch-api-cardholders-id-) or\n[POST](cardholders#post-api-cardholders-id-)."},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"serverDisplayName":{"type":"string"},"notes":{"type":"string"}}}}}}
```

## The CompetencyDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CompetencyDetail":{"title":"Competency detail","description":"[/api/competencies/{id}](competencies#get-api-competencies-id-) returns one of these.\nIt contains the same fields you see when you view or edit a competency in the Configuration\nclient.\n","allOf":[{"$ref":"#/components/schemas/CompetencySummary"},{"type":"object","properties":{"division":{"type":"object","description":"The division containing this competency."},"shortName":{"type":"string"},"expiryNotify":{"type":"boolean","description":"Set if notifications should go out before a cardholder loses this competency.  How\nlong before is in the 'noticePeriod' block.  Who the notification goes to, in\naddition to the cardholder holding the competency, depends on the cardholder's\nrelationships and what notifications are set on the relationship's role.\n"},"noticePeriod":{"description":"How long before expiry Command Centre should send its notification and display 'expiry\ndue' messages on display devices such as a T20 and through this API.\n\nA zero-length notice period means there will be no warning notification.\n","properties":{"units":{"type":"string","enum":["days","weeks","months","years"]},"number":{"type":"integer","minimum":0,"maximum":999,"default":0}}},"defaultExpiry":{"type":"object","description":"In this block, 'expiryType' and 'expiryValue' tell you the expiry time Command\nCentre will use if the operator does not specify one when assigning this competency\nto a cardholder.  It can be unset (meaning the assignment will be unending), a fixed\ndate, or a time period.\n\nIn this example, cardholders will hold the 'Hazardous goods handling' competency\nfor six months after an operator first gives it to them.  In practice, the\noperator should enter the closest end date of the qualifications that allow them\nto handle hazardous goods.  Safety and first aid training, presumably.\n","properties":{"expiryType":{"type":"string","enum":["none","durationdays","durationweeks","durationmonths","durationyears","date"],"default":"none","description":"If 'none', there is no default expiry."},"expiryValue":{"description":"This field will be missing if 'expiryType' is 'none', a string containing a\ndate-time if 'expiryType' is 'date', or an unquoted integer between zero and 999\notherwise.\n\nZero is a valid value.  Because durations are always rounded up to shortly\nbefore midnight, an expiryValue of zero means that the competency will be active\nfor the rest of the day on which the operator grants it.\n"}}},"defaultAccess":{"type":"string","enum":["noAccess","readOnly","fullAccess"],"default":"fullAccess","description":"This is the access that operators will have to cardholders' assignments of this\ncompetency if the operator is not a member of an operator group that overrides it.\nCheck the operator group's 'Competency' tab in the Configuration Client.\n"}}}]},"CompetencySummary":{"title":"Competency summary","description":"The competency search at `/api/competencies` returns an array of these.  The object contains\nsome of what you get from a competency's detail page at `/api/competencies/{id}`, linked as\nthe href in this object.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the identifier to use when assigning a competency to a cardholder in a\n[PATCH](cardholders#patch-api-cardholders-id-) or\n[POST](cardholders#post-api-cardholders-id-)."},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"serverDisplayName":{"type":"string"},"notes":{"type":"string"}}}}}}
```

## The Divisions object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"Divisions":{"type":"object","description":"Calls inside `/api/divisions/` return this object, which is simply a named array of\nobjects each containing some information about a division.\n","properties":{"results":{"type":"array","description":"An array of division objects.","items":{"$ref":"#/components/schemas/Division"}},"next":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"A site generally does not have too many divisions, but if yours does and you do not get\nthem all in the first page, follow this link to get more.  Repeat until the results do\nnot contain a `next` link.\n"}}},"Division":{"type":"object","description":"When a REST call returns the division of a Command Centre item such as a cardholder or access\ngroup, or when you ask it for the divisions in which an operator has a particular privilege,\nit will give an href inside `/divisions/`.  Following that href will return one of these.\n","properties":{"href":{"type":"string","description":"A self reference.","format":"uri-reference"},"id":{"type":"string","description":"The alphanumeric ID of the division.  Use this ID in the `division` filter when requesting\nevents.\n"},"name":{"type":"string","description":"The division's name."},"description":{"type":"string","description":"The division's description.  New in 8.50.  Not sent by default;  ask for it with `fields`."},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"parent":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"An object containing an href to the division entity representing the current division's\nparent.\n\nAll divisions except the root division have a parent.\n"},"visitorManagement":{"type":"object","description":"An object containing the division's visitor management configuration.  It only appears if\nyou ask for it with `fields=visitorManagement` and if your operator has the necessary\nprivilege ('View Site', 'Edit Site', 'View Visits', 'Edit Visits', or 'Manage\nReceptions').\n","properties":{"active":{"type":"boolean","description":"If present and true, this division has its own visitor management configuration.\nOtherwise it uses its parent's.  The same thing is indicated by the presence or\nabsence of the `visitorTypes` block.\n"},"visitorTypes":{"type":"array","description":"This is an array of items, each containing a 'visitor type'.  A visitor type\ncomprises three things:  an access group, to which visitor management will add every\nvisitor as soon as they are on the visit, host access groups, to one of which the\nhost cardholder must belong, and visitor access groups, to which Command Centre will\nadd a visitor when they sign in.\n\nWhen creating a visit you must pick a visitor type that is in the same division as\nthe visit's reception.  The visitor type you pick determines which host you can\nassign (he or she must be a member of at least one of the visitor type's host access\ngroups) and which visitor access groups you can assign (they must be in the visitor\ntype's list of visitor access groups).\n","items":{"type":"object","properties":{"href":{"type":"string","description":"This is the href you should use for a visitor type when you create or update a\nvisit.\n\nIt is only used for identification:  GETting it will 404.\n","format":"uri-reference"},"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}},"description":"The name and href of an access group.\n\nCommand Centre will add cardholders to this access group as soon as you add\nthem to a visit of this type.  The purpose of this group is to grant access to\nPDFs for personal data that will help them sign in on the day, such as\npassport and driver's licence numbers, and photos.\n"},"hostAccessGroups":{"type":"array","description":"Names and hrefs of more access groups.  When you create or modify a visit of\nthis type, its host cardholder must belong to one of these.\n\nA host is the cardholder Command Centre notifies when a visitor arrives, and\nis ultimately responsible for the visitor while on site.\n","items":{"type":"object","properties":{"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}}}},"visitorAccessGroups":{"type":"array","description":"An array of access groups.\n\nCommand Centre will add visitors to a visit's 'visitor access groups' when\nthey sign in.  Their purpose is to grant visitors access through the site's\ndoors so that they can move around the site.\n\nWhen creating a visit using this visitor type, you can only pick visitor\naccess groups from this list.\n\nThe server puts each group's name and href inside a block called\n`accessGroup`, rather than in the root of the array element, to allow for\nexpansion in a future version.\n","items":{"type":"object","properties":{"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}},"description":"The name and href of an access group.  Command Centre will add the\nvisitors on the visit to this access group when they sign in.\n"}}}}}}}}}}}}}}
```

## The Division object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"Division":{"type":"object","description":"When a REST call returns the division of a Command Centre item such as a cardholder or access\ngroup, or when you ask it for the divisions in which an operator has a particular privilege,\nit will give an href inside `/divisions/`.  Following that href will return one of these.\n","properties":{"href":{"type":"string","description":"A self reference.","format":"uri-reference"},"id":{"type":"string","description":"The alphanumeric ID of the division.  Use this ID in the `division` filter when requesting\nevents.\n"},"name":{"type":"string","description":"The division's name."},"description":{"type":"string","description":"The division's description.  New in 8.50.  Not sent by default;  ask for it with `fields`."},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"parent":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"An object containing an href to the division entity representing the current division's\nparent.\n\nAll divisions except the root division have a parent.\n"},"visitorManagement":{"type":"object","description":"An object containing the division's visitor management configuration.  It only appears if\nyou ask for it with `fields=visitorManagement` and if your operator has the necessary\nprivilege ('View Site', 'Edit Site', 'View Visits', 'Edit Visits', or 'Manage\nReceptions').\n","properties":{"active":{"type":"boolean","description":"If present and true, this division has its own visitor management configuration.\nOtherwise it uses its parent's.  The same thing is indicated by the presence or\nabsence of the `visitorTypes` block.\n"},"visitorTypes":{"type":"array","description":"This is an array of items, each containing a 'visitor type'.  A visitor type\ncomprises three things:  an access group, to which visitor management will add every\nvisitor as soon as they are on the visit, host access groups, to one of which the\nhost cardholder must belong, and visitor access groups, to which Command Centre will\nadd a visitor when they sign in.\n\nWhen creating a visit you must pick a visitor type that is in the same division as\nthe visit's reception.  The visitor type you pick determines which host you can\nassign (he or she must be a member of at least one of the visitor type's host access\ngroups) and which visitor access groups you can assign (they must be in the visitor\ntype's list of visitor access groups).\n","items":{"type":"object","properties":{"href":{"type":"string","description":"This is the href you should use for a visitor type when you create or update a\nvisit.\n\nIt is only used for identification:  GETting it will 404.\n","format":"uri-reference"},"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}},"description":"The name and href of an access group.\n\nCommand Centre will add cardholders to this access group as soon as you add\nthem to a visit of this type.  The purpose of this group is to grant access to\nPDFs for personal data that will help them sign in on the day, such as\npassport and driver's licence numbers, and photos.\n"},"hostAccessGroups":{"type":"array","description":"Names and hrefs of more access groups.  When you create or modify a visit of\nthis type, its host cardholder must belong to one of these.\n\nA host is the cardholder Command Centre notifies when a visitor arrives, and\nis ultimately responsible for the visitor while on site.\n","items":{"type":"object","properties":{"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}}}},"visitorAccessGroups":{"type":"array","description":"An array of access groups.\n\nCommand Centre will add visitors to a visit's 'visitor access groups' when\nthey sign in.  Their purpose is to grant visitors access through the site's\ndoors so that they can move around the site.\n\nWhen creating a visit using this visitor type, you can only pick visitor\naccess groups from this list.\n\nThe server puts each group's name and href inside a block called\n`accessGroup`, rather than in the root of the array element, to allow for\nexpansion in a future version.\n","items":{"type":"object","properties":{"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}},"description":"The name and href of an access group.  Command Centre will add the\nvisitors on the visit to this access group when they sign in.\n"}}}}}}}}}}}}}}
```

## The DivisionPATCHAndPOSTExample object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DivisionPATCHAndPOSTExample":{"title":"Division PATCH and POST example","description":"This is an example of a PATCH you could use to update a division, and a POST you could use\nto create one.\n\nWhen POSTing, `parent` is mandatory.\n","type":"object","properties":{"name":{"type":"string","description":"The division's name.  If you supply a name and another division already exists with that\nname, the call will fail.  If you leave it blank in a POST, Command Centre will pick a\nvalue for you.\n"},"description":{"type":"string","description":"The division's description."},"notes":{"type":"string","description":"A string, able to be much longer than `description`, suitable for holding notes about\nthe division.\n"},"parent":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"An object containing an href to the division entity representing the current division's\nparent.\n\nRequired when creating a new division, because only root divisions can be unparented and\nyou cannot create a new one of those.\n"}}}}}}
```

## The DoorSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DoorSearch":{"title":"Door search","description":"An array of door summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of door summaries.","items":{"$ref":"#/components/schemas/DoorSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"DoorSummary":{"title":"Door summary","description":"`/api/doors` returns an array of these.  It is a subset of what you get from a\ndoor's detail page at `/api/doors/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [door detail](models#doordetail) object for this door.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  This is the ID to use in the\n`source` parameter of [event filters](events#get-api-events)\nwhen you are interested in events originating at this door.\n"},"name":{"type":"string"}}}}}}
```

## The DoorSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DoorSummary":{"title":"Door summary","description":"`/api/doors` returns an array of these.  It is a subset of what you get from a\ndoor's detail page at `/api/doors/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [door detail](models#doordetail) object for this door.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  This is the ID to use in the\n`source` parameter of [event filters](events#get-api-events)\nwhen you are interested in events originating at this door.\n"},"name":{"type":"string"}}}}}}
```

## The DoorDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"DoorDetail":{"title":"Door detail","description":"[/api/doors/{id}](doors#get-api-doors-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/DoorSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this door."},"entryAccessZone":{"type":"object","description":"The name and href of the access zone to which this door allows entry.\n","properties":{"name":{"type":"string"},"href":{"description":"This is the address of the [access zone's\ndetail](models#accesszonedetail) page (which includes a link back here in\nits `doors` array).\n","type":"string","format":"uri-reference"}}},"exitAccessZone":{"type":"object","description":"The name and href of the access zone to which this door allows entry in the reverse\ndirection (from its exit reader).\n\nIt will not appear by default.  You need to ask for it with `fields=exitAccessZone`.\n\nNew to 8.50.\n","properties":{"name":{"type":"string"},"href":{"description":"This is the address of the [access zone's\ndetail](models#accesszonedetail) page (which includes a link back here in\nits `doors` array).\n","type":"string","format":"uri-reference"}}},"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"},"updates":{"type":"object","description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n"},"commands":{"type":"object","description":"An array of commands, each represented by a block containing an href that accepts a\nPOST to send an override.\n\nIf your operator is privileged to override the door's entry zone, and the zone only\nhas one door, there will be 17 more links:  four each of the four access zone modes,\nplus 'cancel'.  Each zone mode has four variants:  with or without PINs, and with or\nwithout an end time.\n\nThis block will only contain the links that your operator is privileged to perform.\nExamples of the privileges you need are in the documentation for the POSTs.\n\nThe zone overrides are not repeated here.\n","properties":{"open":{"type":"object","properties":{"href":{"description":"[POST](doors#post-api-doors-id-open) to this to open this door.","type":"string","format":"uri-reference"}}},"lock":{"type":"object","properties":{"href":{"description":"[POST](doors#post-api-doors-id-lock) to this to lock this door.","type":"string","format":"uri-reference"}}}}},"connectedController":{"type":"object","description":"This block describes this door's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it, if your doors are legion.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because in 9.50 there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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"}}}}}]},"DoorSummary":{"title":"Door summary","description":"`/api/doors` returns an array of these.  It is a subset of what you get from a\ndoor's detail page at `/api/doors/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [door detail](models#doordetail) object for this door.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  This is the ID to use in the\n`source` parameter of [event filters](events#get-api-events)\nwhen you are interested in events originating at this door.\n"},"name":{"type":"string"}}}}}}
```

## The ElevatorGroupSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"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"}}}}}}
```

## The ElevatorGroupFloorAccessDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"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"}}}}}}
```

## The ElevatorGroupDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"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"}}}}}}
```

## The EventSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EventSearch":{"title":"Event search","description":"`/api/events` and `/api/events/updates` return this structure.","type":"object","properties":{"events":{"type":"array","description":"A list of event summaries.","items":{"$ref":"#/components/schemas/EventSummary"}},"previous":{"type":"object","description":"Follow this link to make a non-blocking call to collect the previous page of events (in\norder of arrival).  It will return an empty page if you have already received the first\nevent in the database.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"next":{"type":"object","description":"Follow this link to make a non-blocking call to collect the next page of events, moving\nforward in arrival time.  It will return an empty page if no more events are available.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"updates":{"type":"object","description":"This is a link to an [updates](events#get-api-events-updates) call.  Follow it to\nmake a blocking call to collect more events.  If there are none, the call will block until\none arrives or the call times out.  This link will contain your column select, pagination,\nand filtering parameters (`fields`, `top`, `after`, `before`, `source`, `type`, etc.) but it drops\n`deadline`.  You need to add that to each call.\n","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"EventSummary":{"title":"Event summary","type":"object","description":"`/api/events` and `/api/events/updates` return an array of these, and `/api/events/{id}`\nreturns one with more fields.\n\nThe message and event type in this example indicate an operator attempting to log in with an\nincorrect password, but for the sake of illustration the example also contains references to\nitems that would never appear on such an event.  The card, cardholder, and access zones, for\nexample.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this event, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this event, unique to the site but not across sites.\nOnce allocated they are not re-used, except after totally resetting the server's state\nby restoring the database.\n"},"serverDisplayName":{"type":"string","description":"The host name of this event's origin server, if it was aggregated from a remote host.\nAbsent for local events.\n\nNote that this is not the descriptive name of the remote server's item, but the host name\nused for address resolution.\n\nNew to 8.40.\n"},"time":{"type":"string","format":"date-time","description":"The time the event occurred."},"message":{"type":"string","description":"The event's message."},"occurrences":{"type":"integer","description":"If an event arrives with the same essential properties as a previous event, the server\nwill start counting them.  Each event is still individually addressable and will appear in\nthe API as normal, but the first in the\ngroup will also have this property.  It only appears on the first, and it does not appear\nif the event is a singleton.\n\nIf present on an event's detail or alarm page, there will also be a `lastOccurrenceTime`.\n\nOutside of the `alarm` block, which contains an alarm's state, this is the only field on\nan event that can change.\n","minimum":2},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"alarm":{"type":"object","description":"If an event is also an alarm, this object will contain\nits state and a link to its details page in the alarms controller.\n\nOnly the first event in a group (see the `occurrences` field) can become an alarm.\n","properties":{"state":{"description":"Alarms start unacknowledged.  Acknowledging or processing them changes that.","type":"string","enum":["unacknowledged","acknowledged","processed"]},"href":{"type":"string","format":"uri-reference","description":"Link to the alarm entity corresponding to the event. GET the href for full alarm details."}}},"operator":{"description":"The href and name of the operator or system behind this event.  This will appear when an operator\nhas modified an item.  New in v8.00.\n\nThe item he or she modified will appear in the `modifiedItem` block (added in 8.40).\n\n***Change is coming.***\n\nThe operator may not be a cardholder.  A version of Command Centre after 9.30 will\nreturn events where the operator item is of a different kind.  In that case, the\n`operator` block will also contain a `canonicalTypeName` field telling you what kind of\nitem is at the other end of the href.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the operator who caused this event by editing an item.  New in 8.00."},"name":{"type":"string","description":"The name the operator held at the time.  New in 8.40."}}},"source":{"type":"object","description":"ID and name of the source of the event, as recorded at the time of the event.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event source item.  Search for events with the same source\nas this one with `source=321` in the query parameters.\n"},"name":{"type":"string","description":"This could be different from the current name of the source item."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item.  New in 8.00."}}},"group":{"type":"object","description":"ID and name of the event group this event belongs to.  Do not confuse this with an access\ngroup or operator group:  this is the event type group to which the event's type belongs.\nThere are about 150 and you can list them at\n[/events/groups](events#get-api-events-groups).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event group.  Search for events of the same rough category\nas this one with `type=35` in the query parameters.\n"},"name":{"type":"string","description":"The name of the event group."}}},"type":{"type":"object","description":"ID and name of the event's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event type.  To search for events of the same type as this\nexample, put `type=23035` in the query parameters of\n[/events](events#get-api-events).\n"},"name":{"type":"string","description":"The name of the event type."}}},"eventType":{"description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n","type":"object"},"division":{"type":"object","description":"ID, name, and href of the event's division (which is the division of the event's source\nitem, for most event types).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event's division.  Search for other events from items in\nthe same division as this example by putting `division=2` in the query parameters.\n"},"href":{"type":"string","format":"uri-reference","description":"The link to the division item."},"name":{"type":"string","description":"The division's name.  Added in 8.40."}}},"cardholder":{"type":"object","description":"Summary information about an event's cardholder, if there is one.  This will be the\ncardholder who badged their card at a door in an access event, or the cardholder an\noperator modified in an operator event.  Search for other events related to this example's\ncardholder with `cardholder=325` in the query parameters.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the cardholder entity representing the cardholder of the event.  GET the href\nfor full details.\n"},"id":{"type":"string","description":"The alphanumeric ID of the cardholder associated with this event."},"name":{"type":"string","description":"In versions up to and including 8.10 this is the current name of the cardholder.  In\n8.20 it is the name of the cardholder at the time of the event.\n"},"firstName":{"type":"string","description":"The current value of the firstName field of this cardholder.  Added in 8.20."},"lastName":{"type":"string","description":"The current value of the lastName field of this cardholder.  Added in 8.20."}}},"entryAccessZone":{"description":"The name and href of the entry access zone related to the event.  In the case of card\nevents, it is the zone into which a cardholder was attempting to gain access.\n\nThat is true for successful entries, successful exits, and access denials.  Regardless of\nwhether the cardholder badged at the entry or exit reader, this field refers to the zone\nthat he or she attempted to access.\n\nFor example, for 'Card entry granted' events this field will contain the door's entry\nzone, but for 'Card exit granted' events this field will contain the door's _exit_ zone,\nbecause 'exit granted' means the cardholder was in the door's entry zone, badged at its\nexit reader, and was granted access to its exit zone.  Think of it as going through a door\nin its reverse direction.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access zone entity representing the entry access zone related to this\nevent.  GET the href for the access zone's full details.  This will be missing if the\nserver lacks the RESTStatus licence, or your operator lacks the necessary privileges\n(such as 'View Site').\n"},"name":{"type":"string","description":"The current name of the access zone.  Expect a future version of Command Centre to\nchange this to the name of the access zone at the time of the event.\n"},"id":{"type":"string","description":"Deprecated."}}},"exitAccessZone":{"description":"The name and href of the exit access zone related to the event.  In card events, it is the\nzone from which a cardholder was attempting to leave, if the door had an exit zone\nconfigured (many do not).\n\nThat is true for successful entries, successful exits, and access denials.  Regardless of\nwhether the cardholder badged at the entry or exit reader, this field refers to the zone\nthat he or she attempted to leave.\n\nFor example, for 'Card entry granted' events this field will contain the door's exit zone,\nif there was one, but for 'Card exit granted' events this field will contain the door's\n_entry_ zone.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access zone entity representing the exit access zone related to this\nevent.  This will be missing if the server lacks the RESTStatus licence, or your\noperator lacks the necessary privileges (such as 'View Site').\n"},"name":{"type":"string","description":"The current name of the exit access zone.  Expect a future version of Command Centre\nto change this to the name of the exit access zone at the time of the event.\n"},"id":{"type":"string","description":"Deprecated."}}},"door":{"description":"The name and href of the door related to the event.  These are not as common as you may\nthink, because when a door is relevant (to card events, for example) it is usually the\nevent's source, not its door, so it will be in the `source` block.\n\nNew in 8.10.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the entity representing the door related to this event.  This will be missing\nif the server lacks the RESTStatus licence, or your operator lacks the necessary\nprivileges (such as 'View Site').\n"},"name":{"type":"string","description":"The name the door had when the event occurred."}}},"accessGroup":{"description":"The href of the access group that a cardholder just gained or lost in a 'Membership\nActivated' or 'Membership Expired' event.  Those happen when a group membership's 'from'\nor 'until' time passes.\n\nDEPRECATED for the events generated when an operator creates, modifies, or deletes an\naccess group.  Use the 'modifiedItem' field instead (new in 8.40).\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access group related to this event."}}},"card":{"description":"Details of the card associated with the event.\n\nVersions prior to 8.60 returned this block and a card number of zero for all access\nevents, even if they did not involve a credential (after a person entered their user code\nat a keypad, for example).  Version 8.60 does not return this block for such events.\n","type":"object","properties":{"facilityCode":{"type":"string","description":"The card's facility code at the time of the event expressed as one letter followed by\nup to five digits.\n"},"number":{"type":"string","description":"The card's number at the time of the event.  Despite the name it may not necessarily\nbe an actual number; mobile card numbers are arbitrary strings, for example.\n\nNote that card numbers are not guaranteed unique.  The combination of facility code,\nissue level, and card number will be unique for card types that have a facility code\nand issue level.\n\nBefore 8.60 this number was a signed 32-bit integer, so numeric card numbers greater\nthan 2^31 came out negative and mobile card numbers were arbitrary.  In 8.60 numeric\ncard numbers are positive and mobile card numbers are their ID strings, which\noperators can set to anything, and default to GUIDs.\n"},"issueLevel":{"type":"integer","description":"The issue level of the card at the time.\n"}}},"modifiedItem":{"description":"The href and type of the item that an operator created, changed, or deleted, for those\nkinds of events.\n\nNew in 8.40.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the item that this event modified.  Watch for 404s:  this link will be here\neven for deleted items.\n"},"type":{"type":"object","properties":{"id":{"type":"string","description":"A short alphanum identifying the item's type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"}}}}},"next":{"description":"The URL to the search that will return the page of events following this one.  It will\ninclude your search filters and pagination parameters.\n\nThis link is intended for integrations that take great gulps of events and send them to a\ndownstream system.  If it suffers a problem in the middle of a result set, it needs to\nrecord where in the event trail it got up to so that when it restarts it will not miss or\nduplicate events.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"previous":{"description":"The URL to the search that will return the page of events preceding this one.  It will\ninclude your search filters and pagination parameters.\n\nThe `previous` link on the first event in a result set will be the same as the `previous`\nlink outside the results, since they both indicate the latest event that preceded the\nresult set.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"updates":{"description":"The URL to the [updates](events#get-api-events-updates) call that will return the\npage of events following this one, or wait for one to arrive if there are none.  It will\ninclude your search filters and pagination parameters.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The EventSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EventSummary":{"title":"Event summary","type":"object","description":"`/api/events` and `/api/events/updates` return an array of these, and `/api/events/{id}`\nreturns one with more fields.\n\nThe message and event type in this example indicate an operator attempting to log in with an\nincorrect password, but for the sake of illustration the example also contains references to\nitems that would never appear on such an event.  The card, cardholder, and access zones, for\nexample.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this event, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this event, unique to the site but not across sites.\nOnce allocated they are not re-used, except after totally resetting the server's state\nby restoring the database.\n"},"serverDisplayName":{"type":"string","description":"The host name of this event's origin server, if it was aggregated from a remote host.\nAbsent for local events.\n\nNote that this is not the descriptive name of the remote server's item, but the host name\nused for address resolution.\n\nNew to 8.40.\n"},"time":{"type":"string","format":"date-time","description":"The time the event occurred."},"message":{"type":"string","description":"The event's message."},"occurrences":{"type":"integer","description":"If an event arrives with the same essential properties as a previous event, the server\nwill start counting them.  Each event is still individually addressable and will appear in\nthe API as normal, but the first in the\ngroup will also have this property.  It only appears on the first, and it does not appear\nif the event is a singleton.\n\nIf present on an event's detail or alarm page, there will also be a `lastOccurrenceTime`.\n\nOutside of the `alarm` block, which contains an alarm's state, this is the only field on\nan event that can change.\n","minimum":2},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"alarm":{"type":"object","description":"If an event is also an alarm, this object will contain\nits state and a link to its details page in the alarms controller.\n\nOnly the first event in a group (see the `occurrences` field) can become an alarm.\n","properties":{"state":{"description":"Alarms start unacknowledged.  Acknowledging or processing them changes that.","type":"string","enum":["unacknowledged","acknowledged","processed"]},"href":{"type":"string","format":"uri-reference","description":"Link to the alarm entity corresponding to the event. GET the href for full alarm details."}}},"operator":{"description":"The href and name of the operator or system behind this event.  This will appear when an operator\nhas modified an item.  New in v8.00.\n\nThe item he or she modified will appear in the `modifiedItem` block (added in 8.40).\n\n***Change is coming.***\n\nThe operator may not be a cardholder.  A version of Command Centre after 9.30 will\nreturn events where the operator item is of a different kind.  In that case, the\n`operator` block will also contain a `canonicalTypeName` field telling you what kind of\nitem is at the other end of the href.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the operator who caused this event by editing an item.  New in 8.00."},"name":{"type":"string","description":"The name the operator held at the time.  New in 8.40."}}},"source":{"type":"object","description":"ID and name of the source of the event, as recorded at the time of the event.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event source item.  Search for events with the same source\nas this one with `source=321` in the query parameters.\n"},"name":{"type":"string","description":"This could be different from the current name of the source item."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item.  New in 8.00."}}},"group":{"type":"object","description":"ID and name of the event group this event belongs to.  Do not confuse this with an access\ngroup or operator group:  this is the event type group to which the event's type belongs.\nThere are about 150 and you can list them at\n[/events/groups](events#get-api-events-groups).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event group.  Search for events of the same rough category\nas this one with `type=35` in the query parameters.\n"},"name":{"type":"string","description":"The name of the event group."}}},"type":{"type":"object","description":"ID and name of the event's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event type.  To search for events of the same type as this\nexample, put `type=23035` in the query parameters of\n[/events](events#get-api-events).\n"},"name":{"type":"string","description":"The name of the event type."}}},"eventType":{"description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n","type":"object"},"division":{"type":"object","description":"ID, name, and href of the event's division (which is the division of the event's source\nitem, for most event types).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event's division.  Search for other events from items in\nthe same division as this example by putting `division=2` in the query parameters.\n"},"href":{"type":"string","format":"uri-reference","description":"The link to the division item."},"name":{"type":"string","description":"The division's name.  Added in 8.40."}}},"cardholder":{"type":"object","description":"Summary information about an event's cardholder, if there is one.  This will be the\ncardholder who badged their card at a door in an access event, or the cardholder an\noperator modified in an operator event.  Search for other events related to this example's\ncardholder with `cardholder=325` in the query parameters.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the cardholder entity representing the cardholder of the event.  GET the href\nfor full details.\n"},"id":{"type":"string","description":"The alphanumeric ID of the cardholder associated with this event."},"name":{"type":"string","description":"In versions up to and including 8.10 this is the current name of the cardholder.  In\n8.20 it is the name of the cardholder at the time of the event.\n"},"firstName":{"type":"string","description":"The current value of the firstName field of this cardholder.  Added in 8.20."},"lastName":{"type":"string","description":"The current value of the lastName field of this cardholder.  Added in 8.20."}}},"entryAccessZone":{"description":"The name and href of the entry access zone related to the event.  In the case of card\nevents, it is the zone into which a cardholder was attempting to gain access.\n\nThat is true for successful entries, successful exits, and access denials.  Regardless of\nwhether the cardholder badged at the entry or exit reader, this field refers to the zone\nthat he or she attempted to access.\n\nFor example, for 'Card entry granted' events this field will contain the door's entry\nzone, but for 'Card exit granted' events this field will contain the door's _exit_ zone,\nbecause 'exit granted' means the cardholder was in the door's entry zone, badged at its\nexit reader, and was granted access to its exit zone.  Think of it as going through a door\nin its reverse direction.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access zone entity representing the entry access zone related to this\nevent.  GET the href for the access zone's full details.  This will be missing if the\nserver lacks the RESTStatus licence, or your operator lacks the necessary privileges\n(such as 'View Site').\n"},"name":{"type":"string","description":"The current name of the access zone.  Expect a future version of Command Centre to\nchange this to the name of the access zone at the time of the event.\n"},"id":{"type":"string","description":"Deprecated."}}},"exitAccessZone":{"description":"The name and href of the exit access zone related to the event.  In card events, it is the\nzone from which a cardholder was attempting to leave, if the door had an exit zone\nconfigured (many do not).\n\nThat is true for successful entries, successful exits, and access denials.  Regardless of\nwhether the cardholder badged at the entry or exit reader, this field refers to the zone\nthat he or she attempted to leave.\n\nFor example, for 'Card entry granted' events this field will contain the door's exit zone,\nif there was one, but for 'Card exit granted' events this field will contain the door's\n_entry_ zone.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access zone entity representing the exit access zone related to this\nevent.  This will be missing if the server lacks the RESTStatus licence, or your\noperator lacks the necessary privileges (such as 'View Site').\n"},"name":{"type":"string","description":"The current name of the exit access zone.  Expect a future version of Command Centre\nto change this to the name of the exit access zone at the time of the event.\n"},"id":{"type":"string","description":"Deprecated."}}},"door":{"description":"The name and href of the door related to the event.  These are not as common as you may\nthink, because when a door is relevant (to card events, for example) it is usually the\nevent's source, not its door, so it will be in the `source` block.\n\nNew in 8.10.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the entity representing the door related to this event.  This will be missing\nif the server lacks the RESTStatus licence, or your operator lacks the necessary\nprivileges (such as 'View Site').\n"},"name":{"type":"string","description":"The name the door had when the event occurred."}}},"accessGroup":{"description":"The href of the access group that a cardholder just gained or lost in a 'Membership\nActivated' or 'Membership Expired' event.  Those happen when a group membership's 'from'\nor 'until' time passes.\n\nDEPRECATED for the events generated when an operator creates, modifies, or deletes an\naccess group.  Use the 'modifiedItem' field instead (new in 8.40).\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access group related to this event."}}},"card":{"description":"Details of the card associated with the event.\n\nVersions prior to 8.60 returned this block and a card number of zero for all access\nevents, even if they did not involve a credential (after a person entered their user code\nat a keypad, for example).  Version 8.60 does not return this block for such events.\n","type":"object","properties":{"facilityCode":{"type":"string","description":"The card's facility code at the time of the event expressed as one letter followed by\nup to five digits.\n"},"number":{"type":"string","description":"The card's number at the time of the event.  Despite the name it may not necessarily\nbe an actual number; mobile card numbers are arbitrary strings, for example.\n\nNote that card numbers are not guaranteed unique.  The combination of facility code,\nissue level, and card number will be unique for card types that have a facility code\nand issue level.\n\nBefore 8.60 this number was a signed 32-bit integer, so numeric card numbers greater\nthan 2^31 came out negative and mobile card numbers were arbitrary.  In 8.60 numeric\ncard numbers are positive and mobile card numbers are their ID strings, which\noperators can set to anything, and default to GUIDs.\n"},"issueLevel":{"type":"integer","description":"The issue level of the card at the time.\n"}}},"modifiedItem":{"description":"The href and type of the item that an operator created, changed, or deleted, for those\nkinds of events.\n\nNew in 8.40.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the item that this event modified.  Watch for 404s:  this link will be here\neven for deleted items.\n"},"type":{"type":"object","properties":{"id":{"type":"string","description":"A short alphanum identifying the item's type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"}}}}},"next":{"description":"The URL to the search that will return the page of events following this one.  It will\ninclude your search filters and pagination parameters.\n\nThis link is intended for integrations that take great gulps of events and send them to a\ndownstream system.  If it suffers a problem in the middle of a result set, it needs to\nrecord where in the event trail it got up to so that when it restarts it will not miss or\nduplicate events.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"previous":{"description":"The URL to the search that will return the page of events preceding this one.  It will\ninclude your search filters and pagination parameters.\n\nThe `previous` link on the first event in a result set will be the same as the `previous`\nlink outside the results, since they both indicate the latest event that preceded the\nresult set.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"updates":{"description":"The URL to the [updates](events#get-api-events-updates) call that will return the\npage of events following this one, or wait for one to arrive if there are none.  It will\ninclude your search filters and pagination parameters.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The EventDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EventDetail":{"title":"Event detail","description":"[/api/events/{id}](events#get-api-events-id-) returns one of these.  It contains\neverything from the event summary results, plus some extra fields that are too expensive to\ncompute and return for large result sets.\n\nLike the example in the [summary](models#alarmsummary), this example is forced:  no\nactual Command Centre event will contain all of these fields.\n","allOf":[{"$ref":"#/components/schemas/EventSummary"},{"type":"object","properties":{"lastOccurrenceTime":{"type":"string","format":"date-time","description":"When the event has occurred multiple times due to flooding, this will show the time it\noccurred most recently.  It only appears with `occurrences`, and you will only see it\non the first event in a group.\n"},"details":{"type":"string","description":"The full event details text.  This may be up to 2048 UTF-8 characters, each of which\ncould (theoretically) be four bytes long.\n"},"location":{"type":"object","description":"Added in 9.00, this block gathers together information present in about 80 different event\ntypes that contain a cardholder's location, presenting it in a consistent way.\n\nIt allows a client that is interested in movements to extract what it needs\nwithout needing to know what event types to look for or how they represent:\n\n  * the cardholder whose location the event contains,\n  * the access zone that they started in before the event, and\n  * the access zone or reception where they ended up.\n\nThe location block will only be in a result if you ask for it using the `fields` query\nparameter.\n","properties":{"type":{"type":"string","enum":["moved","observed","denied"],"description":"\nThis enum divides location events into three types:\n\n`moved` means a cardholder moved through a door from one zone to another.  Whether\nan operator moved them using our software, or they did it themselves using a\nplastic card, a mobile credential, biometrics, a QR code, a vehicle plate, or\nsomething implemented by a third-party integration, provided they were granted\naccess, this field's value will be `moved`.\n\n`observed` means they did something that indicated their location, such as logging\nin to a workstation or an alarms terminal, but they did not move.\n\n`denied` means the cardholder authenticated successfully and requested access at a\ndoor but failed the access check.  It also appears on some event types where the\ncardholder did not successfully authenticate; for those events there will be no\n`cardholder` block, covered next.\n"},"cardholder":{"type":"object","description":"\nA block describing the cardholder whose location is recorded by the event.\n\nIt will be missing if the cardholder did not successfully authenticate:  perhaps\nthey used their card but did not complete a second factor.  In most cases, though,\nif a cardholder does not authenticate properly (gets their PIN wrong, for example)\nthere will be no `location` block at all.\n","properties":{"name":{"type":"string","description":"The cardholder's name at the time of the event."},"href":{"type":"string","format":"uri-reference","description":"The cardholder item's href.  This will only be present if the cardholder\nhas not been deleted and your operator has the right to view it.\n"}}},"beforeLocation":{"description":"The href and name of the access zone or reception that the cardholder was in\nbefore this event occurred.  Future versions of Command Centre may add more item\ntypes as \"before locations\" so check its canonical type name, covered in the\n`afterLocation` description below.\n\nThe before location is only useful (and present) for 'moved'-type events, which\nhappen when a cardholder changes location.  For 'observed' and 'denied'-type\nevents, which happen when a cardholder does not move, `afterLocation` shows where\nthey were.\n\nThe name was correct at the time of the event.  It may be missing.\n\nThe href will be missing if your operator does not have the right to view the\nlocation.  That also happens when it is deleted.\n\nIf the cardholder moved from outside there will be a field in this block called\n`outside` with the value `true`, and `canonicaltypeName` and `href` will be\nmissing.\n"},"afterLocation":{"description":"The href and name of the item that indicates the cardholder's location after\nthe event.  For 'observed' and 'denied'-type events, this is also where they\nstarted.\n\nFor 'moved' and 'denied' events in 9.00 it will be an access zone or reception.\n\nFor 'observed' events it could be a workstation or an alarms terminal at which the\nperson authenticated.\n\nFuture versions of Command Centre may add more item types.  So that you can branch\non them, this block and `beforeLocation` contain a field called\n`canonicalTypeName`.  The values it returns are fixed:  it is safe to make\ndecisions based on the value.  We will add new values as Command Centre grows, but\nafter its first appearance an item type's `canonicalTypeName` will not change.\n\nCommon canonical type names are `accesszone`, `reception`, `workstation`, and (for\na T20 alarms terminal that uses the H-Bus protocol) `hbusterminal`.  You can get\nthe full list with the [item types](items#get-api-items-types).\n\nIf they moved \"outside the system\" (entering through a door with no entry zone, or\nexiting through a door with no exit zone), there will be no href or canonical\ntype, but there will be a field called `outside` with the value `true`.\n\nThe href will also be missing if your operator does not have the right to view\ntheir new location.\n\nIf present, the item's name was correct at the time of the event.  It may have\nchanged since.  It will be missing for some event types such as 15583, which\nhappens when an operator moves a cardholder outside the system using an\noperational client.\n"}}}}}]},"EventSummary":{"title":"Event summary","type":"object","description":"`/api/events` and `/api/events/updates` return an array of these, and `/api/events/{id}`\nreturns one with more fields.\n\nThe message and event type in this example indicate an operator attempting to log in with an\nincorrect password, but for the sake of illustration the example also contains references to\nitems that would never appear on such an event.  The card, cardholder, and access zones, for\nexample.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the details of this event, also usable as an identifier.  It is not globally\nunique but it is unique to the site and, barring a database restore, it will not be\nrecycled by another event or alarm.\n"},"id":{"type":"string","description":"An alphanumeric identifier for this event, unique to the site but not across sites.\nOnce allocated they are not re-used, except after totally resetting the server's state\nby restoring the database.\n"},"serverDisplayName":{"type":"string","description":"The host name of this event's origin server, if it was aggregated from a remote host.\nAbsent for local events.\n\nNote that this is not the descriptive name of the remote server's item, but the host name\nused for address resolution.\n\nNew to 8.40.\n"},"time":{"type":"string","format":"date-time","description":"The time the event occurred."},"message":{"type":"string","description":"The event's message."},"occurrences":{"type":"integer","description":"If an event arrives with the same essential properties as a previous event, the server\nwill start counting them.  Each event is still individually addressable and will appear in\nthe API as normal, but the first in the\ngroup will also have this property.  It only appears on the first, and it does not appear\nif the event is a singleton.\n\nIf present on an event's detail or alarm page, there will also be a `lastOccurrenceTime`.\n\nOutside of the `alarm` block, which contains an alarm's state, this is the only field on\nan event that can change.\n","minimum":2},"priority":{"type":"integer","description":"Numeric priority.  9 is critical and 0 is not an event.","minimum":0,"maximum":9},"alarm":{"type":"object","description":"If an event is also an alarm, this object will contain\nits state and a link to its details page in the alarms controller.\n\nOnly the first event in a group (see the `occurrences` field) can become an alarm.\n","properties":{"state":{"description":"Alarms start unacknowledged.  Acknowledging or processing them changes that.","type":"string","enum":["unacknowledged","acknowledged","processed"]},"href":{"type":"string","format":"uri-reference","description":"Link to the alarm entity corresponding to the event. GET the href for full alarm details."}}},"operator":{"description":"The href and name of the operator or system behind this event.  This will appear when an operator\nhas modified an item.  New in v8.00.\n\nThe item he or she modified will appear in the `modifiedItem` block (added in 8.40).\n\n***Change is coming.***\n\nThe operator may not be a cardholder.  A version of Command Centre after 9.30 will\nreturn events where the operator item is of a different kind.  In that case, the\n`operator` block will also contain a `canonicalTypeName` field telling you what kind of\nitem is at the other end of the href.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the operator who caused this event by editing an item.  New in 8.00."},"name":{"type":"string","description":"The name the operator held at the time.  New in 8.40."}}},"source":{"type":"object","description":"ID and name of the source of the event, as recorded at the time of the event.","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event source item.  Search for events with the same source\nas this one with `source=321` in the query parameters.\n"},"name":{"type":"string","description":"This could be different from the current name of the source item."},"href":{"type":"string","format":"uri-reference","description":"Link to the source item.  New in 8.00."}}},"group":{"type":"object","description":"ID and name of the event group this event belongs to.  Do not confuse this with an access\ngroup or operator group:  this is the event type group to which the event's type belongs.\nThere are about 150 and you can list them at\n[/events/groups](events#get-api-events-groups).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event group.  Search for events of the same rough category\nas this one with `type=35` in the query parameters.\n"},"name":{"type":"string","description":"The name of the event group."}}},"type":{"type":"object","description":"ID and name of the event's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event type.  To search for events of the same type as this\nexample, put `type=23035` in the query parameters of\n[/events](events#get-api-events).\n"},"name":{"type":"string","description":"The name of the event type."}}},"eventType":{"description":"ID and name of the event's or alarm's type.  There is a long list of them at\n[/events/groups](events#get-api-events-groups).\n\nUnlike the `type` field, this has the same format in an event as it does in an alarm.\n\nAdded in 8.90.  Because it is a new field, it does not appear by default.  Ask for it using\nthe `fields` parameter.\n","type":"object"},"division":{"type":"object","description":"ID, name, and href of the event's division (which is the division of the event's source\nitem, for most event types).\n","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event's division.  Search for other events from items in\nthe same division as this example by putting `division=2` in the query parameters.\n"},"href":{"type":"string","format":"uri-reference","description":"The link to the division item."},"name":{"type":"string","description":"The division's name.  Added in 8.40."}}},"cardholder":{"type":"object","description":"Summary information about an event's cardholder, if there is one.  This will be the\ncardholder who badged their card at a door in an access event, or the cardholder an\noperator modified in an operator event.  Search for other events related to this example's\ncardholder with `cardholder=325` in the query parameters.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the cardholder entity representing the cardholder of the event.  GET the href\nfor full details.\n"},"id":{"type":"string","description":"The alphanumeric ID of the cardholder associated with this event."},"name":{"type":"string","description":"In versions up to and including 8.10 this is the current name of the cardholder.  In\n8.20 it is the name of the cardholder at the time of the event.\n"},"firstName":{"type":"string","description":"The current value of the firstName field of this cardholder.  Added in 8.20."},"lastName":{"type":"string","description":"The current value of the lastName field of this cardholder.  Added in 8.20."}}},"entryAccessZone":{"description":"The name and href of the entry access zone related to the event.  In the case of card\nevents, it is the zone into which a cardholder was attempting to gain access.\n\nThat is true for successful entries, successful exits, and access denials.  Regardless of\nwhether the cardholder badged at the entry or exit reader, this field refers to the zone\nthat he or she attempted to access.\n\nFor example, for 'Card entry granted' events this field will contain the door's entry\nzone, but for 'Card exit granted' events this field will contain the door's _exit_ zone,\nbecause 'exit granted' means the cardholder was in the door's entry zone, badged at its\nexit reader, and was granted access to its exit zone.  Think of it as going through a door\nin its reverse direction.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access zone entity representing the entry access zone related to this\nevent.  GET the href for the access zone's full details.  This will be missing if the\nserver lacks the RESTStatus licence, or your operator lacks the necessary privileges\n(such as 'View Site').\n"},"name":{"type":"string","description":"The current name of the access zone.  Expect a future version of Command Centre to\nchange this to the name of the access zone at the time of the event.\n"},"id":{"type":"string","description":"Deprecated."}}},"exitAccessZone":{"description":"The name and href of the exit access zone related to the event.  In card events, it is the\nzone from which a cardholder was attempting to leave, if the door had an exit zone\nconfigured (many do not).\n\nThat is true for successful entries, successful exits, and access denials.  Regardless of\nwhether the cardholder badged at the entry or exit reader, this field refers to the zone\nthat he or she attempted to leave.\n\nFor example, for 'Card entry granted' events this field will contain the door's exit zone,\nif there was one, but for 'Card exit granted' events this field will contain the door's\n_entry_ zone.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access zone entity representing the exit access zone related to this\nevent.  This will be missing if the server lacks the RESTStatus licence, or your\noperator lacks the necessary privileges (such as 'View Site').\n"},"name":{"type":"string","description":"The current name of the exit access zone.  Expect a future version of Command Centre\nto change this to the name of the exit access zone at the time of the event.\n"},"id":{"type":"string","description":"Deprecated."}}},"door":{"description":"The name and href of the door related to the event.  These are not as common as you may\nthink, because when a door is relevant (to card events, for example) it is usually the\nevent's source, not its door, so it will be in the `source` block.\n\nNew in 8.10.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the entity representing the door related to this event.  This will be missing\nif the server lacks the RESTStatus licence, or your operator lacks the necessary\nprivileges (such as 'View Site').\n"},"name":{"type":"string","description":"The name the door had when the event occurred."}}},"accessGroup":{"description":"The href of the access group that a cardholder just gained or lost in a 'Membership\nActivated' or 'Membership Expired' event.  Those happen when a group membership's 'from'\nor 'until' time passes.\n\nDEPRECATED for the events generated when an operator creates, modifies, or deletes an\naccess group.  Use the 'modifiedItem' field instead (new in 8.40).\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the access group related to this event."}}},"card":{"description":"Details of the card associated with the event.\n\nVersions prior to 8.60 returned this block and a card number of zero for all access\nevents, even if they did not involve a credential (after a person entered their user code\nat a keypad, for example).  Version 8.60 does not return this block for such events.\n","type":"object","properties":{"facilityCode":{"type":"string","description":"The card's facility code at the time of the event expressed as one letter followed by\nup to five digits.\n"},"number":{"type":"string","description":"The card's number at the time of the event.  Despite the name it may not necessarily\nbe an actual number; mobile card numbers are arbitrary strings, for example.\n\nNote that card numbers are not guaranteed unique.  The combination of facility code,\nissue level, and card number will be unique for card types that have a facility code\nand issue level.\n\nBefore 8.60 this number was a signed 32-bit integer, so numeric card numbers greater\nthan 2^31 came out negative and mobile card numbers were arbitrary.  In 8.60 numeric\ncard numbers are positive and mobile card numbers are their ID strings, which\noperators can set to anything, and default to GUIDs.\n"},"issueLevel":{"type":"integer","description":"The issue level of the card at the time.\n"}}},"modifiedItem":{"description":"The href and type of the item that an operator created, changed, or deleted, for those\nkinds of events.\n\nNew in 8.40.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Link to the item that this event modified.  Watch for 404s:  this link will be here\neven for deleted items.\n"},"type":{"type":"object","properties":{"id":{"type":"string","description":"A short alphanum identifying the item's type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"}}}}},"next":{"description":"The URL to the search that will return the page of events following this one.  It will\ninclude your search filters and pagination parameters.\n\nThis link is intended for integrations that take great gulps of events and send them to a\ndownstream system.  If it suffers a problem in the middle of a result set, it needs to\nrecord where in the event trail it got up to so that when it restarts it will not miss or\nduplicate events.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"previous":{"description":"The URL to the search that will return the page of events preceding this one.  It will\ninclude your search filters and pagination parameters.\n\nThe `previous` link on the first event in a result set will be the same as the `previous`\nlink outside the results, since they both indicate the latest event that preceded the\nresult set.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"updates":{"description":"The URL to the [updates](events#get-api-events-updates) call that will return the\npage of events following this one, or wait for one to arrive if there are none.  It will\ninclude your search filters and pagination parameters.\n\nNew to 8.70.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}}
```

## The EventPOSTBody object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EventPOSTBody":{"title":"Event POST body","required":["eventType"],"properties":{"type":{"deprecated":true,"description":"A new event must contain either this or (if your server is running 8.90 or later) `eventType`.\nWithout one of them, the POST will fail.\n\nThe event type is mandatory because the server cannot assume a reasonable default, as it\ndoes for the other fields.\n\nIf you send both a `type` block and an `eventType` block to a server running 8.90 or later\nit will use `eventType`.  Versions before 8.90 do not know about `eventType` so they use `type`.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}},"eventType":{"description":"A new event must contain either this or `type`.  Without one of them, the POST will\nfail.\n\nThe event type is mandatory because the server cannot assume a reasonable default, as it\ndoes for the other fields.\n\nIf you send both a `type` block and an `eventType` block to a server running 8.90 or later\nit will use `eventType`.  Versions before 8.90 do not know about `eventType` so they use `type`.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"Take this href from the list of [event types](events#get-api-events-groups).\nNote that you can only use event types in one of the thirty external event groups with\nIDs 57-66 and 190-209.  Command Centre ships with one event type per group, IDs\n4000-4009 and 6010-6029, but you can create 970 more using the External Event Type\nConfiguration utility.\n"}}},"source":{"description":"This block should contain the href of the item you wish to use as the source of your\nevent.  It can be any site item to which your operator has view access including all\nhardware, access zones, fence zones, doors, lockers, car parks, servers, external systems,\nand many other item types.  If you do not supply one Command Centre will use the REST\nClient item identified by the API key in the `Authorization` header.\n\nCardholders cannot be event sources.  To relate a cardholder to your event, use the\n`cardholder` block.\n\nMake sure that your operator has the 'Create Events and Alarms' privilege on this item's\ndivision.  8.90 and later insist on it.\n\nThe API will use the source's division as the event's division.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"Get the href using the API controller for that type of item (such as\n[doors](doors)) or from the more general [item\nsearch](items#get-api-items).\n"}}},"priority":{"type":"integer","minimum":1,"maximum":9,"description":"It is not possible to submit an event with priority zero in the body, but if you submit an\nevent with no priority it will use the one on the event type's action plan, which can be\nzero.\n"},"time":{"type":"string","format":"date-time","description":"Like all other fields in this POST apart from the type, this field is optional.  If you\nsend it, it must be in the format described [here](text-encoding).\n\nIf you do not send this, the server will use the time that it received your request\n(its \"now\").\n"},"message":{"type":"string","description":"This is the first thing an operator will see when they look at this event.  Some\ninteractive clients do not give it a lot of room on screen so put the important\nparts of your message first.  It has a limit of 1024 characters.\n"},"details":{"type":"string","description":"Command Centre will attach this string to event, as it does the message, but\noperators will have to look more closely at the event to see it.  On the upside,\nit can be longer than the message:  2048 characters in 8.10.\n"},"cardholder":{"description":"If you wish to attach a cardholder to your event, link it here.  Reports can show or\nfilter by the cardholder.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any cardholder to which your operator has view access.  Get\nthe href from the [cardholders controller](cardholders).\n"}}},"operator":{"description":"If you wish to attach an operator to your event, link it here.  Like the cardholder,\nreports can show or filter by the operator.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any cardholder to which your operator has view access.  It\ndoes not need to be an operator (a member of an operator group).\n"}}},"entryAccessZone":{"description":"If you wish to attach an access zone to your event, link it here.  Reports can filter by\nand show the entry access zone on events.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any access zone to which your operator has view access.  Get\nthe href using the [access zones controller](tag-Access-Zones) or from\n`/items`.\n"}}},"accessGroup":{"description":"If you wish to attach an access group to your event, link it here.\n\nUnlike cardholders, operators, and entry access zones, access groups do not appear in\nCommand Centre activity reports.  You can add a filter to restrict an activity report by\naccess groups, but the group that allowed an event into the report will not appear in a\ncolumn.\n\nLike all the other items you link to your event it will, of course, appear when you GET\nthe event from the API later.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any access group to which your operator has view access.\nGet the href using the [groups controller](access-groups) or\nthe [items controller](items).\n"}}},"lockerBank":{"description":"If you wish to attach a locker bank to your event, link it here.\n\nLike an event's access group, you can filter a Command Centre activity report to events\nthat involve a locker bank, but the bank will not appear in the report itself.\n\nIf you link both a locker and a locker bank to an event, Command Centre does not require\nthat the locker is in the locker bank, but you may find that downstream reporting software\nmisbehaves when it is not.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any locker bank to which your operator has view access.  Get\nthe href using the [locker banks](lockers) calls or the more general\n[items](items) routes.\n"}}},"locker":{"description":"If you wish to link a locker to your event, do it here.  Like an event's access group and\nlocker bank, you can filter a Command Centre activity report to events that involve a\nlocker, but the locker will not appear in the report itself.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any locker your operator can view.  Get the href from the\n[items](items) controller or the `lockers` field of [a locker\nbank](models#lockerbankdetail).\n"}}},"door":{"description":"If you wish to link a door to your event for later extraction or a report filter, do it\nhere.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This can be the href of any door your operator can see.  Get it with a\n[doors](doors) call or a more general [items\nsearch](items#get-api-items).\n"}}}}}}}}
```

## The EventGroups object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"EventGroups":{"title":"Event groups","description":"Calls to `/api/events/groups/` return this object, which is a named array of groups of event types.","type":"object","properties":{"eventGroups":{"type":"array","description":"An array of event group objects.  There will be about 150.  Most groups contain fewer than 100 event types;  one contains around 200.","items":{"type":"object","properties":{"id":{"type":"string","description":"The alphanumeric ID of the event group.  Use this ID in the `group` filter when requesting events."},"name":{"type":"string","description":"The name of the event group."},"eventTypes":{"type":"array","description":"An array of all the event types in the group.","items":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"},"id":{"type":"string","description":"The alphanumeric ID of the event type.  Use this ID in the `type` filter when requesting events."},"name":{"type":"string"}}}}}}}}}}}}
```

## The FenceZoneSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"FenceZoneSearch":{"title":"Fence zone search","description":"An array of fence zone summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of Fence Zone summaries.","items":{"$ref":"#/components/schemas/FenceZoneSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"FenceZoneSummary":{"title":"Fence zone summary","description":"`/api/fence_zones` returns an array of these.  It is a subset of what you get from a\nfence zone's detail page at `/api/fence_zones/{id}` (linked as the href in this\nobject).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [fence zone detail](models#fencezonedetail) object for this fence\nzone.  This is Command Centre's identifier for this fence zone:  use it whenever you need\nto specify a fence zone in REST operations.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events\nto those coming from particular fence zones.\n"},"name":{"type":"string"}}}}}}
```

## The FenceZoneSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"FenceZoneSummary":{"title":"Fence zone summary","description":"`/api/fence_zones` returns an array of these.  It is a subset of what you get from a\nfence zone's detail page at `/api/fence_zones/{id}` (linked as the href in this\nobject).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [fence zone detail](models#fencezonedetail) object for this fence\nzone.  This is Command Centre's identifier for this fence zone:  use it whenever you need\nto specify a fence zone in REST operations.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events\nto those coming from particular fence zones.\n"},"name":{"type":"string"}}}}}}
```

## The FenceZoneDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"FenceZoneDetail":{"title":"Fence zone detail","description":"[/api/fence_zones/{id}](fence-zones#get-api-fence_zones-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/FenceZoneSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this Fence Zone."},"voltage":{"type":"integer","minimum":0,"description":"The last known voltage on the fence, in volts, to the nearest 100 volts, provided the\nfence zone is online and the REST server is subscribed to its updates.  See the [item\nstatus](item-status) section for how to make sure of that.\n\nThis value is only up to date when the fence zone is on (shown in the status flags)\nand has emitted at least one pulse.\n\nVoltages are not displayed by default, because of the caveats around their use.  You\nmust ask for them using the 'fields' parameter: `?fields=voltage,...`.\n"},"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"},"updates":{"type":"object","description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n"},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"commands":{"type":"object","description":"A block of commands, each represented by a block containing an href that\naccepts a POST that will send an override to the fence zone, changing its\nstate.\n\nIt will be missing if your operator is not privileged to override the fence zone.\n\nSee the section 'Creating a Fence Zone' in the Configuration client help\nfor a description of fence zone states.\n","properties":{"on":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-on) to this to energise this\nfence zone.\n","type":"string","format":"uri-reference"}}},"off":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-off) to this to deactivate this\nfence zone.\n","type":"string","format":"uri-reference"}}},"shunt":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-shunt) to this to shunt this\nfence zone.\n","type":"string","format":"uri-reference"}}},"unshunt":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-unshunt) to this to restore\ncommunication with the fence zone.\n","type":"string","format":"uri-reference"}}},"highVoltage":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-high_voltage) to this to set this\nfence zone to 'high voltage' mode.\n","type":"string","format":"uri-reference"}}},"lowFeel":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-low_feel) to this to set this\nfence zone to 'low feel' mode.\n","type":"string","format":"uri-reference"}}},"cancel":{"type":"object","properties":{"href":{"description":"[POST](fence-zones#post-api-fence_zones-id-cancel) to this to cancel an\nactive override on the fence zone.\n","type":"string","format":"uri-reference"}}}}}}}]},"FenceZoneSummary":{"title":"Fence zone summary","description":"`/api/fence_zones` returns an array of these.  It is a subset of what you get from a\nfence zone's detail page at `/api/fence_zones/{id}` (linked as the href in this\nobject).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [fence zone detail](models#fencezonedetail) object for this fence\nzone.  This is Command Centre's identifier for this fence zone:  use it whenever you need\nto specify a fence zone in REST operations.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events\nto those coming from particular fence zones.\n"},"name":{"type":"string"}}}}}}
```

## The InputSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"InputSearch":{"title":"Input search","description":"An array of input summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of input summaries.","items":{"$ref":"#/components/schemas/InputSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"InputSummary":{"title":"Input summary","description":"`/api/inputs` returns an array of these.  It is a subset of what you get from an\ninput's detail page at `/api/inputs/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [input detail](models#inputdetail) object for this input.\n"},"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) if you are only\ninterested in events from particular inputs.\n"},"name":{"type":"string"}}}}}}
```

## The InputSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"InputSummary":{"title":"Input summary","description":"`/api/inputs` returns an array of these.  It is a subset of what you get from an\ninput's detail page at `/api/inputs/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [input detail](models#inputdetail) object for this input.\n"},"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) if you are only\ninterested in events from particular inputs.\n"},"name":{"type":"string"}}}}}}
```

## The InputDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"InputDetail":{"title":"Input detail","description":"[/api/inputs/{id}](inputs#get-api-inputs-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/InputSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this input."},"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"},"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"},"updates":{"type":"object","description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n"},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"commands":{"type":"object","description":"A block of commands, each represented by a block containing an href that accepts a\nPOST that will send an override to the input.\n\nIt will be missing if your operator does not have a privilege that allows overriding\nthe input (examples of which are in the documentation for the POSTs).\n","properties":{"shunt":{"type":"object","properties":{"href":{"description":"[POST](inputs#post-api-inputs-id-shunt) to this to shunt the input.\n","type":"string","format":"uri-reference"}}},"unshunt":{"type":"object","properties":{"href":{"description":"[POST](inputs#post-api-inputs-id-unshunt) to this to stop shunting the\ninput.\n","type":"string","format":"uri-reference"}}},"isolate":{"type":"object","properties":{"href":{"description":"[POST](inputs#post-api-inputs-id-isolate) to this to isolate the input.\nIsolated inputs do not prevent alarm zones from arming.\n\nThe link will be missing if the input is shunted.\n","type":"string","format":"uri-reference"}}},"deisolate":{"type":"object","properties":{"href":{"description":"[POST](inputs#post-api-inputs-id-deisolate) to this to stop isolating\nthe input.  The link will be missing if the input is shunted.\n","type":"string","format":"uri-reference"}}}}}}}]},"InputSummary":{"title":"Input summary","description":"`/api/inputs` returns an array of these.  It is a subset of what you get from an\ninput's detail page at `/api/inputs/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [input detail](models#inputdetail) object for this input.\n"},"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) if you are only\ninterested in events from particular inputs.\n"},"name":{"type":"string"}}}}}}
```

## The InterlockGroupSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"InterlockGroupSearch":{"title":"Interlock group search","description":"**API support for interlocks is still in development and may change in future versions.**\n\nAn array of interlock group summaries and a `next` link for more.\n","properties":{"results":{"type":"array","description":"An array of interlock group summaries.","items":{"$ref":"#/components/schemas/InterlockGroupSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"InterlockGroupSummary":{"title":"Interlock group summary","description":"**API support for interlocks is still in development and may change in future versions.**\n\n`/api/interlock_groups` returns an array of these.  It is a subset of what you get from an\ninterlock's details page at `/api/interlock_groups/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [interlock group detail](models#interlockgroupdetail) object for this\nitem.\n"},"name":{"type":"string"}}}}}}
```

## The InterlockGroupSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"InterlockGroupSummary":{"title":"Interlock group summary","description":"**API support for interlocks is still in development and may change in future versions.**\n\n`/api/interlock_groups` returns an array of these.  It is a subset of what you get from an\ninterlock's details page at `/api/interlock_groups/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [interlock group detail](models#interlockgroupdetail) object for this\nitem.\n"},"name":{"type":"string"}}}}}}
```

## The InterlockGroupDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"InterlockGroupDetail":{"title":"Interlock group detail","description":"**API support for interlocks is still in development and may change in future versions.**\n\n[/api/interlock_groups/{id}](interlock-groups#get-api-interlock_groups-id-) returns one of these.\n\nSome of the fields will not come from the server unless you request them via the `fields`\nquery parameter.\n","allOf":[{"$ref":"#/components/schemas/InterlockGroupSummary"},{"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"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this interlock group."},"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"},"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"},"updates":{"type":"object","description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n"},"statusText":{"description":"This field contains a translated multi-line human-readable description of the item's status. See the `statusFlags` field for notes on when you should ask for this field and how to keep it up to date.","type":"string"},"status":{"description":"This field contains the `statusText` field with line endings turned into spaces to make a one-line string.  See the `statusFlags` field for notes on when you should ask for this field and how to keep it up to date.","type":"string"},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"commands":{"type":"object","description":"A block of commands, each represented by a block containing an href that accepts a\nPOST that will send an override to the interlock.\n\nIt will be missing if your operator does not have a privilege that allows overriding\nthe interlock (examples of which are in the documentation for the POSTs).\n","properties":{"disable":{"type":"object","properties":{"href":{"description":"[POST](interlock-groups#post-api-interlock_groups-id-disable) to this to disable the\ninterlock group, allowing the doors to operate independently.\n","type":"string","format":"uri-reference"}}},"enable":{"type":"object","properties":{"href":{"description":"[POST](interlock-groups#post-api-interlock_groups-id-enable) to re-enable the\ninterlock group, causing its doors to return to interlock behaviour.\n","type":"string","format":"uri-reference"}}}}}}}]},"InterlockGroupSummary":{"title":"Interlock group summary","description":"**API support for interlocks is still in development and may change in future versions.**\n\n`/api/interlock_groups` returns an array of these.  It is a subset of what you get from an\ninterlock's details page at `/api/interlock_groups/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [interlock group detail](models#interlockgroupdetail) object for this\nitem.\n"},"name":{"type":"string"}}}}}}
```

## The ItemSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ItemSearch":{"title":"Item search","type":"object","description":"Calls to `/api/items` return this object.","properties":{"results":{"description":"A list of item objects, each containing the alphanumeric ID of the item, its name, and its type.","type":"array","items":{"$ref":"#/components/schemas/ItemSummary"}},"next":{"type":"object","description":"An href to the next page of results.  Missing if there are no more results.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"ItemSummary":{"title":"Item summary","type":"object","description":"`/api/items` returns an array of these.  Because it can contain an item of any type, it only\ncontains some fields that are common to all item types.\n\n`description` and `shortName` arrived in 9.60.\n","properties":{"id":{"type":"string","description":"Use this ID in the `source` filter when requesting events to limit events to those with\nthat source.  Card events such as 'access granted', for example, have a door as their\nsource.\n"},"name":{"type":"string"},"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"},"description":{"type":"string","description":"In 9.60 and later."},"type":{"type":"object","description":"The `type` object contains the ID and name of the item's type.","properties":{"id":{"type":"string","description":"Use this ID in the `type` filter when requesting items if you wish to restrict the\nresults to items of a certain type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change.  You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"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"},"href":{"type":"string","description":"Reserved for internal use.  Its value changed in version 9.10."}}}}}}
```

## The ItemSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ItemSummary":{"title":"Item summary","type":"object","description":"`/api/items` returns an array of these.  Because it can contain an item of any type, it only\ncontains some fields that are common to all item types.\n\n`description` and `shortName` arrived in 9.60.\n","properties":{"id":{"type":"string","description":"Use this ID in the `source` filter when requesting events to limit events to those with\nthat source.  Card events such as 'access granted', for example, have a door as their\nsource.\n"},"name":{"type":"string"},"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"},"description":{"type":"string","description":"In 9.60 and later."},"type":{"type":"object","description":"The `type` object contains the ID and name of the item's type.","properties":{"id":{"type":"string","description":"Use this ID in the `type` filter when requesting items if you wish to restrict the\nresults to items of a certain type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change.  You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"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"},"href":{"type":"string","description":"Reserved for internal use.  Its value changed in version 9.10."}}}}}}
```

## The ItemDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ItemDetail":{"title":"Item detail","type":"object","description":"A call to `/api/items/{id}` (added in 8.40) returns one of these.  It adds the item's division\nto the summary object.\n","allOf":[{"$ref":"#/components/schemas/ItemSummary"},{"type":"object","properties":{"division":{"type":"object","properties":{"id":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}}}]},"ItemSummary":{"title":"Item summary","type":"object","description":"`/api/items` returns an array of these.  Because it can contain an item of any type, it only\ncontains some fields that are common to all item types.\n\n`description` and `shortName` arrived in 9.60.\n","properties":{"id":{"type":"string","description":"Use this ID in the `source` filter when requesting events to limit events to those with\nthat source.  Card events such as 'access granted', for example, have a door as their\nsource.\n"},"name":{"type":"string"},"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"},"description":{"type":"string","description":"In 9.60 and later."},"type":{"type":"object","description":"The `type` object contains the ID and name of the item's type.","properties":{"id":{"type":"string","description":"Use this ID in the `type` filter when requesting items if you wish to restrict the\nresults to items of a certain type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change.  You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"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"},"href":{"type":"string","description":"Reserved for internal use.  Its value changed in version 9.10."}}}}}}
```

## The ItemTypes object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ItemTypes":{"title":"Item types","type":"object","description":"Calls to `/api/items/types` return this object, an array of item types.","properties":{"itemTypes":{"description":"A list of item types.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The alphanumeric ID of the item type.  Use this ID in the `type` filter when requesting items."},"name":{"type":"string","description":"The human-readable name of the item type.  These strings will change over time as\nGallagher expands its product line, and can change with the server's language\nsettings, so take care if using them for anything except display.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change.  You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}}}}}}}}
```

## The ItemUpdate object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ItemUpdate":{"title":"Item update","type":"object","description":"POSTs and GETs to `/api/items/updates` return this object.  It contains an array of updates\nand a `next` link to collect more.\n\nAdded in 8.30.\n","properties":{"updates":{"description":"A list of items and their statuses.\n\nPrior to v9.50 the first two calls—the POST and the first GET—contain all the items in\nyour subscription (provided they are the types of item that have statuses).  This is\nunnecessary and incurs a significant performance penalty, so in 9.50 that changed.  The\nresults of the POST will contain all the items in your subscription, as before, but the\nfirst GET will not return them all a second time.  Use [this\nalgorithm](items#get-api-items-updates).\n\nOn\nsubsequent GETs it will only contain the items that received status updates since your\nprevious call.  Note that an item will be in this array if it received any status update\nat all, even if the status flags did not change.  Prepare to receive updates that do not\ncontain novel data.\n\nThis array is not paginated:  it could contain every one of the items you put in your\nPOST.\n\nAfter about 50 seconds the call will time out and return an empty array and a `next`\nlink.  When that happens, follow the `next` link just as you would have if there had\nbeen changes.  Do not re-use the URL that returned you the empty array, because that\nwill cause the server to start looking for status changes a point 50 seconds earlier\nthan necessary.  The results will be the same, but the server will have done more work\nto generate them.\n","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The item's ID, from the list you sent in the POST that created this subscription.\n"},"statusFlags":{"type":"array","items":{"type":"string"},"description":"An array of string enumerations (flags) that describe the item's condition in a\nreliable, machine-readable way.\n\nThe item types that the REST API supports (such as fence zones and inputs) have a\nfull set of status flags, described in their own sections of this documentation.\nTo see the values that this enumeration can take, search for headings with 'status\nflags' in their name in those sections.\n\nItems that the REST API does not support yet (such as readers) will return error\nflags if they are in an unusual state, or nothing if they are online and reporting\nnormally.  Therefore an empty array is a good sign.\n"},"statusText":{"type":"string","description":"The state of the item in a multi-line string taken from the server's language pack.\n"},"status":{"type":"string","description":"A one-line version of the status, with details removed if necessary to keep it short.\n"}}}},"next":{"description":"A link to GET more status updates.  Do not wait longer than thirty seconds between\nreceiving this link and using it or your subscription will expire and you will need to\nsubmit another POST to create a new one.\n"}}}}}}
```

## The LockerBankSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"LockerBankSearch":{"title":"Locker bank search","description":"An array of locker bank summaries, and a `next` link for more.\n","properties":{"results":{"type":"array","description":"An array of locker bank summaries.","items":{"$ref":"#/components/schemas/LockerBankSummary"}},"next":{"type":"object","description":"The link to the next page of results.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"LockerBankSummary":{"title":"Locker bank summary","description":"The locker bank search at `/api/locker_banks` returns an array of these.  It is a subset of\nwhat you get from a locker bank's detail page at `/api/locker_banks/{id}` (linked as the href\nin this object).\n\nLike the cardholder and access group summary pages in this API, this contains only\nthe basic information about a locker bank.  It is the result of a search and could\nreturn many items, and we did not want the size getting out of hand.\n\nAlso like the other summary pages in this API, you can add all the fields you want using the\n`fields` query parameter to the API routes that return it.\n\nThe most important field is the href to the detail page, covered next.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the detail page for this locker bank."},"name":{"type":"string"},"shortName":{"type":"string","description":"The bank's short name."},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this locker bank."}}}}}}
```

## The LockerBankSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"LockerBankSummary":{"title":"Locker bank summary","description":"The locker bank search at `/api/locker_banks` returns an array of these.  It is a subset of\nwhat you get from a locker bank's detail page at `/api/locker_banks/{id}` (linked as the href\nin this object).\n\nLike the cardholder and access group summary pages in this API, this contains only\nthe basic information about a locker bank.  It is the result of a search and could\nreturn many items, and we did not want the size getting out of hand.\n\nAlso like the other summary pages in this API, you can add all the fields you want using the\n`fields` query parameter to the API routes that return it.\n\nThe most important field is the href to the detail page, covered next.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to the detail page for this locker bank."},"name":{"type":"string"},"shortName":{"type":"string","description":"The bank's short name."},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this locker bank."}}}}}}
```

## The LockerBankDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"LockerBankDetail":{"title":"Locker bank detail","description":"[/api/locker_banks/{id}](lockers#get-api-locker_banks-id-) returns one of these.  It\ncontains an array of all the lockers in the bank, each of which contains an array of the\ncardholders assigned to that locker.\n\nThis example shows two lockers on the bank, called 'L1' and 'L2'.  L1 has two\ncardholders who can open it:  one for two years, the other for a week in April 2018.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A self-reference."},"name":{"type":"string"},"shortName":{"type":"string"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this locker bank."},"notes":{"type":"string"},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"lockers":{"description":"An array of locker objects, each containing the details of the locker and the\ncardholders who can open it.\n","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"shortName":{"type":"string","description":"A T20 will display this instead of the long name, if it has both."},"description":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the href of the locker.  Use it when creating new assignments in a\ncardholder PATCH or POST.  Trying to GET it will always yield a 404.\n"},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.  Retrieving it takes a little more time\nthan the other fields so only ask for it if you need it.\n\nAdded in 8.50.\n"},"assignments":{"type":"array","description":"A locker can have many assignments.  Each contains a cardholder and up to two dates,\nbetween which the cardholder can open the locker.  If either of the dates is\nmissing, the assignment is unbounded in that direction.\n","items":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the href of a cardholder's assignment to a locker.  Put it in a\n[cardholder PATCH](cardholders#patch-api-cardholders-id-) to update or delete\nit.\n\nYou can also revoke a cardholder's access to this locker by sending a\n[DELETE](cardholders#delete-api-cardholders-id-lockers-assignment_id-) to this href.\n\nIf the site does not have the RESTCardholders licence or your operator does\nnot have the privilege to view the cardholder, this link will not work in a\nDELETE or a cardholder PATCH.\n"},"cardholder":{"type":"object","description":"The name and href of the cardholder assigned to this locker.  It will be\nmissing if the site does not have the RESTCardholders licence or your operator\ndoes not have the privilege to view that cardholder.\n"},"from":{"type":"string","format":"date-time","description":"If missing, the locker assignment has no start time, meaning the cardholder\ncan open the locker provided the 'until' time is in the future.\n"},"until":{"type":"string","format":"date-time","description":"If missing, the locker assignment has no end time, meaning the cardholder can\nopen the locker provided the 'from' time is in the past.\n"}}}},"commands":{"type":"object","description":"Overrideable items return one of these blocks if your operator has the right\nprivilege and the locker is fit to be overridden.  It is a list of commands, each\nrepresented by a block containing an href that accepts a POST that will send an\noverride to the locker, changing its state.\n","properties":{"open":{"type":"object","properties":{"href":{"description":"POST to this URL to send an open override to the locker.  The server will\nignore the POST body.\n","type":"string","format":"uri-reference"}}},"quarantine":{"type":"object","properties":{"href":{"description":"POST to this URL to send a quarantine override to the locker.  Do not send a\nbody with the POST since some server versions use the same POST for\n`quarantineUntil`, which takes a time from the body.\n","type":"string","format":"uri-reference"}}},"quarantineUntil":{"type":"object","properties":{"href":{"description":"POST to this URL to send an override to the locker that will quarantine it\nuntil a timestamp you send [in the body](rest.html#definition-OverrideEndTime).\n","type":"string","format":"uri-reference"}}},"cancelQuarantine":{"type":"object","properties":{"href":{"description":"POST to this URL to send a quarantine cancel override to the locker.  The\nserver will ignore the POST body.\n","type":"string","format":"uri-reference"}}}}},"updates":{"description":"This is not a default field:  you must ask for it by adding `lockers.updates` to\nthe `fields` query parameter.  Since it can only monitor one locker at a time we\ndiscourage its use in favour of [bulk status\nmonitoring](items#status-subscriptions).\n"}}}}}}}}}
```

## The LockerDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"LockerDetail":{"title":"Locker detail","description":"[/api/lockers/{id}](lockers#get-api-locker-id-) returns one of these.  It contains some\nbasic data about a locker, its assignments (the cardholders who can open it), and a link to\noverride it open.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A self-reference."},"name":{"type":"string"},"shortName":{"type":"string"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this locker."},"notes":{"type":"string","description":"The notes field is not in the default result set.  You must ask for it using `fields`."},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"assignments":{"type":"array","description":"A locker can have many assignments.  Each contains a cardholder and up to two dates,\nbetween which the cardholder can open the locker.  If either of the dates is missing, the\nassignment is unbounded in that direction.\n","items":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the href of a cardholder's assignment to a locker.  Put it in a [cardholder\nPATCH](cardholders#patch-api-cardholders-id-) to update or delete it.\n\nYou can also revoke a cardholder's access to this locker by sending a\n[DELETE](cardholders#delete-api-cardholders-id-lockers-assignment_id-) to this\nhref.\n\nIf the site does not have the RESTCardholders licence or your operator does not have\nthe privilege to view the cardholder, this link will not work in a DELETE or a\ncardholder PATCH.\n"},"cardholder":{"type":"object","description":"The name and href of the cardholder assigned to this locker.  It will be missing if\nthe site does not have the RESTCardholders licence or your operator does not have\nthe privilege to view that cardholder.\n"},"from":{"type":"string","format":"date-time","description":"If missing, the locker assignment has no start time, meaning the cardholder can open\nthe locker while the 'until' time is in the future.\n"},"until":{"type":"string","format":"date-time","description":"If missing, the locker assignment has no end time, meaning the cardholder can open\nthe locker after the 'from' time.\n"}}}},"commands":{"type":"object","description":"Overrideable items return one of these blocks if your operator has the right\nprivilege and the locker is fit to be overridden.  It is a list of commands, each\nrepresented by a block containing an href that accepts a POST that will send an\noverride to the locker, changing its state.\n","properties":{"open":{"type":"object","properties":{"href":{"description":"POST to this URL to send an open override to the locker.  The server will\nignore the POST body.\n","type":"string","format":"uri-reference"}}},"quarantine":{"type":"object","properties":{"href":{"description":"POST to this URL to send a quarantine override to the locker.  Do not send a\nbody with the POST since some server versions use the same POST for\n`quarantineUntil`, which takes a time from the body.\n","type":"string","format":"uri-reference"}}},"quarantineUntil":{"type":"object","properties":{"href":{"description":"POST to this URL to send an override to the locker that will quarantine it\nuntil a timestamp you send [in the body](rest.html#definition-OverrideEndTime).\n","type":"string","format":"uri-reference"}}},"cancelQuarantine":{"type":"object","properties":{"href":{"description":"POST to this URL to send a quarantine cancel override to the locker.  The\nserver will ignore the POST body.\n","type":"string","format":"uri-reference"}}}}},"updates":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Follow the URL in the href inside this block to receive the locker's current status, then\nfollow the `next` link in the results to long poll for changes to that status.\n\n`updates` was added to the lockers controller in 9.10 for consistency with other\ncontrollers, but we discourage its use in favour of [bulk status\nmonitoring](items#status-subscriptions).\n\nAlthough a locker's status includes 'free' or 'allocated', allocating or un-allocating a\nlocker does not cause the API to report a change of status.  Opening, closing,\nquarantining, and unquarantining a locker do.\n"}}}}}}
```

## The MacroSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"MacroSearch":{"title":"Macro search","description":"An array of macro summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of macro summaries.","items":{"$ref":"#/components/schemas/MacroSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"MacroSummary":{"title":"Macro summary","description":"`/api/macros` returns an array of these.  It is a subset of what you get from a\nmacro's detail page at `/api/macros/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [macro detail](models#macrodetail) object for this macro.\n"},"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) if you are only\ninterested in events from particular macros (which would be unusual, since macros do not\ngenerate many events).\n"},"name":{"type":"string"}}}}}}
```

## The MacroSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"MacroSummary":{"title":"Macro summary","description":"`/api/macros` returns an array of these.  It is a subset of what you get from a\nmacro's detail page at `/api/macros/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [macro detail](models#macrodetail) object for this macro.\n"},"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) if you are only\ninterested in events from particular macros (which would be unusual, since macros do not\ngenerate many events).\n"},"name":{"type":"string"}}}}}}
```

## The MacroDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"MacroDetail":{"title":"Macro detail","description":"[/api/macros/{id}](macros#get-api-macros-id-) returns one of these.\n\nIt contains a block called `updates`.  This is reserved for future development and its\nbehaviour will change in later versions of Command Centre.\n","allOf":[{"$ref":"#/components/schemas/MacroSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this Macro."},"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"},"commands":{"type":"object","description":"The only thing you can do to a macro via REST is run it, so this block only contains one command, and only if your operator is privileged to do that.","properties":{"run":{"type":"object","properties":{"href":{"description":"[POST](macros#post-api-macros-id-run) to this to run this macro.\n","type":"string","format":"uri-reference"}}}}}}}]},"MacroSummary":{"title":"Macro summary","description":"`/api/macros` returns an array of these.  It is a subset of what you get from a\nmacro's detail page at `/api/macros/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [macro detail](models#macrodetail) object for this macro.\n"},"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) if you are only\ninterested in events from particular macros (which would be unusual, since macros do not\ngenerate many events).\n"},"name":{"type":"string"}}}}}}
```

## The OperatorGroupSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OperatorGroupSearch":{"title":"Operator group search","description":"An array of operator group summaries and a `next` link for\nmore.\n","properties":{"results":{"type":"array","description":"An array of operator group summaries.","items":{"$ref":"#/components/schemas/OperatorGroupSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"OperatorGroupSummary":{"title":"Operator group summary","description":"The operator group search at `/api/operator_groups` returns an array of these, and\n`/api/operator_groups/{id}` (linked as the href in this object) returns one with more fields.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [operator group detail](models#operatorgroupdetail) object for this\noperator group.\n"},"name":{"type":"string"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"}}}}}}
```

## The OperatorGroupSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OperatorGroupSummary":{"title":"Operator group summary","description":"The operator group search at `/api/operator_groups` returns an array of these, and\n`/api/operator_groups/{id}` (linked as the href in this object) returns one with more fields.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [operator group detail](models#operatorgroupdetail) object for this\noperator group.\n"},"name":{"type":"string"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"}}}}}}
```

## The OperatorGroupDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OperatorGroupDetail":{"title":"Operator group detail","description":"[/api/operator_groups/{id}](operator-groups#get-api-operator_groups-id-) returns one\nof these.  In addition to the basic item details such as division and description, it lists\nthe divisions in which it grants privileges to its members.\n","allOf":[{"$ref":"#/components/schemas/OperatorGroupSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division that contains this operator group.  This has no bearing on the divisions\nto which this operator group grants privileges:  that is `divisions`.\n"},"cardholders":{"type":"object","description":"Following this link lists the group's [cardholder\nmembers](operator-groups#get-api-operator_groups-id-cardholders).\n"},"divisions":{"description":"An array containing the divisions in which this operator group grants its privileges.\n","type":"array","items":{"type":"object","properties":{"division":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}}}}}}}]},"OperatorGroupSummary":{"title":"Operator group summary","description":"The operator group search at `/api/operator_groups` returns an array of these, and\n`/api/operator_groups/{id}` (linked as the href in this object) returns one with more fields.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [operator group detail](models#operatorgroupdetail) object for this\noperator group.\n"},"name":{"type":"string"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"}}}}}}
```

## The OperatorGroupMembership object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OperatorGroupMembership":{"title":"Operator group membership","description":"Returned in an array by\n[/api/operator_groups/{id}/cardholders](operator-groups#get-api-operator_groups-id-cardholders),\ncontaining cardholders who are members of a particular operator group.\n\nEach item contains the cardholder's name and (if your operator has the privilege to view\nthat cardholder) an href to the cardholder record.  8.70 added an href that you can use to\ndelete the operator group membership.\n\n[PATCH](cardholders#patch-api-cardholders-id-) the href in the cardholder block if\nyou want to change anything about that cardholder.  The operator groups they are in, for\nexample.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"[DELETE](cardholders#delete-api-cardholders-id-operator_groups-membership_id-)\nthis URL to remove the cardholder from this operator group.\n\nDELETE is the only verb you can use on this URL.  GET will return a 404.\n\nIt is not a default field.  If you want it, you need to request it using the `fields`\nquery parameter.\n\nAdded in 8.70.\n"},"cardholder":{"type":"object","description":"The name and href of the member cardholder."}}}}}}
```

## The OutputSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OutputSearch":{"title":"Output search","description":"An array of output summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of output summaries.","items":{"$ref":"#/components/schemas/OutputSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"OutputSummary":{"title":"Output summary","description":"`/api/outputs` returns an array of these.  It is a subset of what you get from an\noutput's detail page at `/api/outputs/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [output detail](models#outputdetail) object for this output.\n"},"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) if you are only\ninterested in events from particular outputs.\n"},"name":{"type":"string"}}}}}}
```

## The OutputSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OutputSummary":{"title":"Output summary","description":"`/api/outputs` returns an array of these.  It is a subset of what you get from an\noutput's detail page at `/api/outputs/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [output detail](models#outputdetail) object for this output.\n"},"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) if you are only\ninterested in events from particular outputs.\n"},"name":{"type":"string"}}}}}}
```

## The OutputDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"OutputDetail":{"title":"Output detail","description":"[/api/outputs/{id}](outputs#get-api-outputs-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/OutputSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this output."},"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"},"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"},"updates":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n"},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n"},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"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).\n"}}},"commands":{"type":"object","description":"A block of commands keyed by a fixed enumeration given below.  The values are blocks\ncontaining an href that accepts a POST that will send an override to the output,\nturning it on or off.\n\nIt will be missing if your operator does not have a privilege that allows overriding\nthe output (examples of which are in the documentation for the POSTs).\n","properties":{"on":{"type":"object","properties":{"href":{"description":"[POST](outputs#post-api-outputs-id-on) to this to close this output.\n","type":"string","format":"uri-reference"}}},"onUntil":{"type":"object","properties":{"href":{"description":"[POST](outputs#post-api-outputs-id-on) to this to close this output for\na fixed time.\n","type":"string","format":"uri-reference"}}},"off":{"type":"object","properties":{"href":{"description":"[POST](outputs#post-api-outputs-id-off) to this to open this output.\n","type":"string","format":"uri-reference"}}},"offUntil":{"type":"object","properties":{"href":{"description":"[POST](outputs#post-api-outputs-id-off) to this to open this output for\na fixed time.\n","type":"string","format":"uri-reference"}}},"pulse":{"type":"object","properties":{"href":{"description":"[POST](outputs#post-api-outputs-id-pulse) to this to close this output\nfor its pulse time.\n\nThis link will only be here if the output is set to pulse when activated.\n\nAdded in 8.50.\n","type":"string","format":"uri-reference"}}}}}}}]},"OutputSummary":{"title":"Output summary","description":"`/api/outputs` returns an array of these.  It is a subset of what you get from an\noutput's detail page at `/api/outputs/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [output detail](models#outputdetail) object for this output.\n"},"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) if you are only\ninterested in events from particular outputs.\n"},"name":{"type":"string"}}}}}}
```

## The PDFDefinitionSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"PDFDefinitionSearch":{"title":"PDF definition search","description":"An array of PDF definition summaries, and a `next` link for more.\n","properties":{"results":{"type":"array","description":"An array of PDF definition summaries.","items":{"$ref":"#/components/schemas/PDFDefinition"}},"next":{"type":"object","description":"The link to the next page of results.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"PDFDefinition":{"title":"PDF definition","description":"`/api/personal_data_fields` returns an array of these.  By default it gives you just the\nbasics about a PDF:  its ID, href, name, and (if it is remote) the name of its home server.\nBy using the `fields` parameter you can add more.\n","properties":{"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.  Use it to filter cardholder searches\nand to add your external ID to the results of an event search.\n"},"name":{"type":"string"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this PDF definition.  Required when creating one.\n"},"type":{"type":"string","description":"The type of PDF: string, image, email address, etc.\n\nRequired when creating a new PDF definition, but ignored when PATCHing one since a PDF's\ntype is fixed once set.\n","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]},"default":{"description":"This is the value that new cardholders will receive, if not supplied by the creating\nclient.  Required for 'required' PDFs.\n\nThis field will be missing if there is no default value.\n\nTo clear the default, send the blank string `\"\"`.\n","type":"string"},"required":{"type":"boolean","default":false,"description":"If true, every cardholder with this PDF must have a value for it.  No blanks allowed.\n"},"unique":{"type":"boolean","default":false,"description":"If true, every cardholder with a value for this PDF must have a different value.\n\nAfter 8.70 this will not show for date and image PDFs, because it can never be true for\nthem.\n"},"defaultAccess":{"type":"string","enum":["noAccess","revealable","readOnly","writeOnly","revealAndEdit","fullAccess"],"default":"fullAccess","description":"This is the access that operators will have to cardholders' values of this PDF if the\noperator is not a member of an operator group that overrides it.  Check the operator\ngroup's 'Personal data' tab in the Configuration Client.\n\n`revealable`, `revealAndEdit`, and `writeOnly` are new to 8.90.\n"},"operatorAccess":{"readOnly":true,"description":"This is the access that your operator has to cardholders' values of this PDF, including the\npermissions granted by this operator's operator groups.  You will only\nget this field if you ask for it with the `fields` parameter.\n\nREST clients cannot see the value of a PDF if its effective access is one of the two\n`reveal` values or `writeOnly`.  To see these PDF values, put the REST Client item's\noperator into an operator group that improves the PDF's access level, to (say)\n`readOnly`.\n\nNew in 8.80.  `revealable`, `revealAndEdit`, and `writeOnly` new to 8.90.\n","type":"string","enum":["noAccess","revealable","readOnly","writeOnly","revealAndEdit","fullAccess"]},"sortPriority":{"description":"This is called 'sort order' in the Configuration Client.  Interactive clients use this\nnumber to order the list of PDFs on a cardholder.  It has no effect on access control or\nthis API.\n","type":"integer"},"accessGroups":{"readOnly":true,"description":"This array contains a block for each access group that gives this PDF to its members.\nEach block contains the group's name, and if the operator has read access to the\ngroup, its href.\n","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}},"notificationDefault":{"description":"This value is copied to the 'notification' flag on a cardholder's value for this PDF when\nthey first gain membership of one of this PDF's access groups.  It will only appear for\nPDF types that can receive notifications (email addresses and mobile numbers), and only if\nyou ask for it with the `fields` parameter.  The server will ignore it if you send it in a\nPOST or PATCH to a PDF that is not email or mobile.\n\nNew in 8.50.\n","type":"boolean"},"regex":{"description":"This is the regular expression that a string-valued PDF value must match before Command\nCentre will accept it on a cardholder.\n\nTo remove the requirement that PDF values match a regular expression, send the empty\nstring `\"\"`.\n","type":"string"},"regexDescription":{"description":"Regular expressions often need explaining.","type":"string"},"imageWidth":{"description":"The maximum width of an image stored in this PDF, in pixels, for image PDF types.  You\nwill only get this field if you ask for it with the `fields` parameter.\n\nYou can set this on a new PDF definition but not change it on an existing definition.\n\nNew in 8.50.\n","type":"integer"},"imageHeight":{"description":"The maximum height of an image stored in this PDF, in pixels, for image PDF types.  You\nwill only get this field if you ask for it with the `fields` parameter.\n\nYou can set this on a new PDF definition but not change it on an existing definition.\n\nNew in 8.50.\n","type":"integer"},"imageFormat":{"deprecated":true,"description":"Whether this image PDF stores BMPs, JPEGs, or PNGs.  You will only get this field if you\nask for it with the `fields` parameter.\n\nNew in 8.50.  Deprecated in 8.70 by `contentType`, which is more standard.\n","type":"string","enum":["bmp","jpg","png"]},"contentType":{"description":"Whether this image PDF stores BMPs, JPEGs, or PNGs.  You will only get this field if you\nask for it with the `fields` parameter.\n\nYou can set this on a new PDF definition but not change it on an existing definition.\n\nNew in 8.70.\n","type":"string","enum":["image/bmp","image/jpeg","image/png"]},"isProfileImage":{"description":"True if and only if this PDF holds images and it is set as a profile image.\n\nUnlike many other properties of an image PDF, this can be changed at will.\n\nNew in 8.70.\n","type":"boolean"}}}}}}
```

## The PDFDefinition object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"PDFDefinition":{"title":"PDF definition","description":"`/api/personal_data_fields` returns an array of these.  By default it gives you just the\nbasics about a PDF:  its ID, href, name, and (if it is remote) the name of its home server.\nBy using the `fields` parameter you can add more.\n","properties":{"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.  Use it to filter cardholder searches\nand to add your external ID to the results of an event search.\n"},"name":{"type":"string"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this PDF definition.  Required when creating one.\n"},"type":{"type":"string","description":"The type of PDF: string, image, email address, etc.\n\nRequired when creating a new PDF definition, but ignored when PATCHing one since a PDF's\ntype is fixed once set.\n","enum":["string","image","strEnum","numeric","date","address","phone","email","mobile"]},"default":{"description":"This is the value that new cardholders will receive, if not supplied by the creating\nclient.  Required for 'required' PDFs.\n\nThis field will be missing if there is no default value.\n\nTo clear the default, send the blank string `\"\"`.\n","type":"string"},"required":{"type":"boolean","default":false,"description":"If true, every cardholder with this PDF must have a value for it.  No blanks allowed.\n"},"unique":{"type":"boolean","default":false,"description":"If true, every cardholder with a value for this PDF must have a different value.\n\nAfter 8.70 this will not show for date and image PDFs, because it can never be true for\nthem.\n"},"defaultAccess":{"type":"string","enum":["noAccess","revealable","readOnly","writeOnly","revealAndEdit","fullAccess"],"default":"fullAccess","description":"This is the access that operators will have to cardholders' values of this PDF if the\noperator is not a member of an operator group that overrides it.  Check the operator\ngroup's 'Personal data' tab in the Configuration Client.\n\n`revealable`, `revealAndEdit`, and `writeOnly` are new to 8.90.\n"},"operatorAccess":{"readOnly":true,"description":"This is the access that your operator has to cardholders' values of this PDF, including the\npermissions granted by this operator's operator groups.  You will only\nget this field if you ask for it with the `fields` parameter.\n\nREST clients cannot see the value of a PDF if its effective access is one of the two\n`reveal` values or `writeOnly`.  To see these PDF values, put the REST Client item's\noperator into an operator group that improves the PDF's access level, to (say)\n`readOnly`.\n\nNew in 8.80.  `revealable`, `revealAndEdit`, and `writeOnly` new to 8.90.\n","type":"string","enum":["noAccess","revealable","readOnly","writeOnly","revealAndEdit","fullAccess"]},"sortPriority":{"description":"This is called 'sort order' in the Configuration Client.  Interactive clients use this\nnumber to order the list of PDFs on a cardholder.  It has no effect on access control or\nthis API.\n","type":"integer"},"accessGroups":{"readOnly":true,"description":"This array contains a block for each access group that gives this PDF to its members.\nEach block contains the group's name, and if the operator has read access to the\ngroup, its href.\n","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}},"notificationDefault":{"description":"This value is copied to the 'notification' flag on a cardholder's value for this PDF when\nthey first gain membership of one of this PDF's access groups.  It will only appear for\nPDF types that can receive notifications (email addresses and mobile numbers), and only if\nyou ask for it with the `fields` parameter.  The server will ignore it if you send it in a\nPOST or PATCH to a PDF that is not email or mobile.\n\nNew in 8.50.\n","type":"boolean"},"regex":{"description":"This is the regular expression that a string-valued PDF value must match before Command\nCentre will accept it on a cardholder.\n\nTo remove the requirement that PDF values match a regular expression, send the empty\nstring `\"\"`.\n","type":"string"},"regexDescription":{"description":"Regular expressions often need explaining.","type":"string"},"imageWidth":{"description":"The maximum width of an image stored in this PDF, in pixels, for image PDF types.  You\nwill only get this field if you ask for it with the `fields` parameter.\n\nYou can set this on a new PDF definition but not change it on an existing definition.\n\nNew in 8.50.\n","type":"integer"},"imageHeight":{"description":"The maximum height of an image stored in this PDF, in pixels, for image PDF types.  You\nwill only get this field if you ask for it with the `fields` parameter.\n\nYou can set this on a new PDF definition but not change it on an existing definition.\n\nNew in 8.50.\n","type":"integer"},"imageFormat":{"deprecated":true,"description":"Whether this image PDF stores BMPs, JPEGs, or PNGs.  You will only get this field if you\nask for it with the `fields` parameter.\n\nNew in 8.50.  Deprecated in 8.70 by `contentType`, which is more standard.\n","type":"string","enum":["bmp","jpg","png"]},"contentType":{"description":"Whether this image PDF stores BMPs, JPEGs, or PNGs.  You will only get this field if you\nask for it with the `fields` parameter.\n\nYou can set this on a new PDF definition but not change it on an existing definition.\n\nNew in 8.70.\n","type":"string","enum":["image/bmp","image/jpeg","image/png"]},"isProfileImage":{"description":"True if and only if this PDF holds images and it is set as a profile image.\n\nUnlike many other properties of an image PDF, this can be changed at will.\n\nNew in 8.70.\n","type":"boolean"}}}}}}
```

## The CHUID object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CHUID":{"description":"This is the model of a CHUID block for a PIV card.  The only difference between this and a\nPIV-I card is the FASC-N.\n","type":"object","required":["hash","fascn"],"properties":{"hash":{"type":"string","description":"This is the hash of the CHUID object, Base64-encoded.  For a 256-bit hash it\nshould be 44 characters long including one `=` pad.  The API will reject a string that is\nnot valid Base64, but it will not verify the hash.\n\nRequired when creating a PIV card in versions up to 8.60.  Optional in 8.70 and later.\n"},"fascn":{"type":"string","description":"This is the FASC-N identifier.  You must supply it when creating a card.\n\nIt must be the same as the card number on a PIV (not PIV-I) card.\n\nOn a PIV-I card, it must not be the same as the card number (and for Federal PIV-I cards\nit will likely begin with fourteen nines).\n"},"orgIdentifier":{"type":"string","description":"Optional."},"duns":{"type":"string","description":"Optional."}}}}}}
```

## The NewPIVCard object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"NewPIVCard":{"title":"New PIV Card","description":"A new PIV card.  You would put this in the `cards` array of a cardholder you were creating with a POST,\nor the `cards.add` array of a cardholder you were modifying with a PATCH.\n","type":"object","required":["type","number","pivData"],"properties":{"type":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"The href of the server's PIV card type.  This documentation has a section called\n\"finding the PIV card type\" if you need it.\n"}}},"status":{"type":"object","properties":{"value":{"type":"string"}}},"number":{"type":"string","description":"While the card number rules on a PIV or PIV-I card type are different from those on other\ntypes, card numbers are still strings, and the API will accept them from you and return\nthem to you in the same way.\n\nPIV card numbers are the FASC-N with hyphens splitting the major components.\n\nPIV-I card numbers are the CHUID's GUID in decimal.\n"},"pivData":{"type":"object","description":"These are the PIV-specific fields that you can set on a new card.  They\nare the same as you [receive from the API](piv-cards#get-api-cardholders-id-%20-PIV-) for\nan existing PIV card except that you do not send a `lastCheckTime`.\n","required":["chuid","contentSigningCert","pivAuthenticationCert"],"properties":{"chuid":{"description":"Required when creating a card, ignored when updating one.\n\nThe FASC-N in the `chuid` block, and its relationship with the card number, is the only\ndifference between PIV and PIV-I cards in Command Centre.\n","$ref":"#/components/schemas/CHUID"},"pivStatus":{"type":"object","description":"The PIV status held in the `type` field in this block is distinct from the generic card\nstatus, which is a different field outside the `pivData` block.\n\nIt is optional.  If you omit it when creating a card, the card will be enabled with a status\nof \"NotChecked\", which—despite how it sounds—is a perfectly valid operating status.  If\nCommand Centre is doing periodic certificate validation, the status will eventually change\n(to 'normal', all going well).\n\nYou should send this block when creating a card only if you are doing your own certificate\nvalidation.\n\nWhen updating an existing card, this is the only field it makes sense to send (specifically,\nthe `type` field inside it).\n\n`type` must be set to one of these values, based on the result of your validation:\n\n  - Normal\n  - Offline\n  - Revoked\n  - Expired\n  - CertInChainRevoked\n  - CertInChainExpired\n  - IssuerSigCertRevoked\n  - IssuerSigCertExpired\n  - NotTrusted\n  - PolicyError\n  - OtherError\n  - NotChecked\n\nIf you set it to any value except 'NotChecked', 'Normal', or 'Offline', Command Centre will consider the\ncard invalid and deactivate it regardless of what you pass as the card status.  You, or\nCommand Centre's periodic certificate validation, may validate the card again later.\n","properties":{"type":{"type":"string","enum":["Normal","Offline","Revoked","Expired","CertInChainRevoked","CertInChainExpired","IssuerSigCertRevoked","IssuerSigCertExpired","NotTrusted","PolicyError","OtherError","NotChecked"]}}},"contentSigningCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card.  The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n\nThis example is shortened to fit on screen.  Real certificates are at least a thousand\ncharacters.\n"},"cardAuthenticationCert":{"type":"string","description":"This contains the CAK, which is necessary for the secure use of contactless cards.  It is\nnot required for contact cards.\n\nOptional when creating a PIV or PIV-I card.  The API will reject your request if this is\npresent and not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"pivAuthenticationCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card.  The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"fingerprints":{"type":"string","description":"If you send this when creating a card, it should be the cardholder's fingerprints contained in\nthe card's Cardholder Fingerprints data object with the error detection code removed:  the\nwhole CBEFF structure including the CBEFF_HEADER, CBEFF_BIOMETRIC_RECORD, and\nCBEFF_SIGNATURE_BLOCK components.  Refer to Section 9 of NIST Special Publication 800-76-2:\nBiometric Data Specification for Personal Identity Verification.\n\nIt is optional.  The API will check that this is Base64, but will not verify that it is\nvalid biometric data.\n"}}}}},"CHUID":{"description":"This is the model of a CHUID block for a PIV card.  The only difference between this and a\nPIV-I card is the FASC-N.\n","type":"object","required":["hash","fascn"],"properties":{"hash":{"type":"string","description":"This is the hash of the CHUID object, Base64-encoded.  For a 256-bit hash it\nshould be 44 characters long including one `=` pad.  The API will reject a string that is\nnot valid Base64, but it will not verify the hash.\n\nRequired when creating a PIV card in versions up to 8.60.  Optional in 8.70 and later.\n"},"fascn":{"type":"string","description":"This is the FASC-N identifier.  You must supply it when creating a card.\n\nIt must be the same as the card number on a PIV (not PIV-I) card.\n\nOn a PIV-I card, it must not be the same as the card number (and for Federal PIV-I cards\nit will likely begin with fourteen nines).\n"},"orgIdentifier":{"type":"string","description":"Optional."},"duns":{"type":"string","description":"Optional."}}}}}}
```

## The ReceptionSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ReceptionSearch":{"title":"Reception search","description":"An array of receptions, and a `next` link for more.\n","properties":{"results":{"type":"array","description":"An array of receptions.","items":{"$ref":"#/components/schemas/Reception"}},"next":{"type":"object","description":"The link to the next page of results.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"Reception":{"description":"`/api/receptions` returns an array of these, and `/api/receptions/{id}` returns one.  Each\ngives you enough about a reception to identify it and use it in a visit:  its href, name, and\n(if you ask for them using the `fields` parameter) its description, default visitor type, and\nnotes.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the href to use when creating a visit.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"description":{"type":"string","description":"Short free-form text.  Searches do not return an item's description - ask for it using the\n`fields` parameter.\n"},"division":{"type":"object","description":"The division containing this reception."},"defaultVisitorType":{"type":"object","description":"Gallagher's visitor management applications use this to pre-fill a UI element prompting\nthe user to pick a visitor type when they are creating a visit for this reception.  The\nserver does not use it.\n"},"notes":{"type":"string","description":"Free-form text.  You will only get this field if you ask for it with the `fields`\nparameter.\n"}}}}}}
```

## The Reception object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"Reception":{"description":"`/api/receptions` returns an array of these, and `/api/receptions/{id}` returns one.  Each\ngives you enough about a reception to identify it and use it in a visit:  its href, name, and\n(if you ask for them using the `fields` parameter) its description, default visitor type, and\nnotes.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the href to use when creating a visit.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"description":{"type":"string","description":"Short free-form text.  Searches do not return an item's description - ask for it using the\n`fields` parameter.\n"},"division":{"type":"object","description":"The division containing this reception."},"defaultVisitorType":{"type":"object","description":"Gallagher's visitor management applications use this to pre-fill a UI element prompting\nthe user to pick a visitor type when they are creating a visit for this reception.  The\nserver does not use it.\n"},"notes":{"type":"string","description":"Free-form text.  You will only get this field if you ask for it with the `fields`\nparameter.\n"}}}}}}
```

## The Redaction object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"Redaction":{"description":"An array of these comes from `GET /cardholders/redactions`.\n","allOf":[{"$ref":"#/components/schemas/CardholderRedaction"},{"type":"object","properties":{"cardholder":{"type":"object","description":"The href of the cardholder whose events or item this redaction should affect.\n\nRequired.\n"},"finished":{"type":"string","description":"When the redaction finished.\n\nWill be missing from pending redactions.\n","format":"date-time"},"message":{"type":"string","description":"Translated string from the redaction's error code.  Will be absent if empty, or if the\nredaction is pending or complete.\n"},"details":{"type":"string","description":"A more detailed description of what went wrong.\n\nNot translated.  Will be absent if empty, or if the redaction is pending or complete.\n"}}}]},"CardholderRedaction":{"title":"Cardholder redaction","description":"These appear in an array in a cardholder object.  Each describes a redaction scheduled for the\ncardholder.\n\nA cardholder can have multiple event redactions pending, because they can operate on events\nfrom different periods, but since a cardholder redaction removes the cardholder item there\ncan be only one.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this URL to cancel this redaction.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"type":{"type":"string","enum":["normalEvents","cardholder"],"description":"Whether this redaction is for cardholder events or cardholder information.\n"},"when":{"description":"When the redaction is meant to happen.  This should be in the future.  If it is in the past,\nthe service returns 400-Bad Request Invalid Start Time.\n\nOptional.  If it is absent, it means to do it asap.\n","type":"string","format":"date-time"},"before":{"description":"For event redactions, do not redact any events after this time.  No effect on cardholder\ninformation redactions.\n\nOptional.\n","type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","inProgress","cancelled","done","failed"],"description":"The status of this redaction.\n"},"redactionOperator":{"description":"A block containing the href and current name of the operator who scheduled the redaction.\n","type":"object"}}}}}}
```

## The RedactionPOST object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"RedactionPOST":{"title":"Redaction POST","description":"POST one of these to schedule a redaction.\n","required":["cardholder","type"],"allOf":[{"$ref":"#/components/schemas/RedactionCommonFields"},{"type":"object","properties":{"when":{"type":"string","description":"When the redaction is meant to happen.  This should be in the future.  If it is in the\npast, the service returns a 400.\n\nOptional.  If it is absent, it means to do it asap.\n","format":"date-time"}}}]},"RedactionCommonFields":{"title":"Redaction shared fields","description":"These fields are common to redaction POSTs and GETs.\n","properties":{"cardholder":{"type":"object","description":"The href of the cardholder whose events or item this redaction should affect.\n\nRequired.\n"},"type":{"type":"string","enum":["normalEvents","cardholder"],"description":"Whether this redaction is for events or cardholder information.\n\nRequired.\n"},"before":{"type":"string","description":"For event redactions, do not redact any events after this time.  No effect on cardholder\ninformation redactions.\n\nOptional.\n","format":"date-time"}}}}}}
```

## The RedactionCommonFields object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"RedactionCommonFields":{"title":"Redaction shared fields","description":"These fields are common to redaction POSTs and GETs.\n","properties":{"cardholder":{"type":"object","description":"The href of the cardholder whose events or item this redaction should affect.\n\nRequired.\n"},"type":{"type":"string","enum":["normalEvents","cardholder"],"description":"Whether this redaction is for events or cardholder information.\n\nRequired.\n"},"before":{"type":"string","description":"For event redactions, do not redact any events after this time.  No effect on cardholder\ninformation redactions.\n\nOptional.\n","format":"date-time"}}}}}}
```

## The Role object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"Role":{"description":"`/api/roles` returns an array of these.  Each element gives you enough about a role to\nidentify it and use it in a cardholder PATCH:  its href, name, description, and (if you ask\nfor them using the `fields` parameter) notes.\n\nIn 9.10 or later you can send one of these in a POST to create a new role, or in a PATCH to\nmodify an existing one.\n","properties":{"name":{"type":"string"},"href":{"readOnly":true,"type":"string","format":"uri-reference","description":"This is the string to use when creating a relationship between cardholders using this\nrole.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this role.  Required in a POST, optional in a PATCH.\n"},"enableCompetencyExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncompetencies are about to expire.\n"},"enableCardExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncards are about to expire.\n"}}}}}}
```

## The ScheduleSearch object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ScheduleSearch":{"title":"Schedule search","type":"object","properties":{"results":{"type":"array","description":"An array of schedule summaries.","items":{"$ref":"#/components/schemas/ScheduleSummary"}},"next":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"The link to the next page.  Absent if you have retrieved them all."}},"description":"An array of schedule summaries, and a `next` link for more."},"ScheduleSummary":{"title":"Schedule summary","type":"object","properties":{"href":{"type":"string","description":"A link to a [schedule detail](models#scheduledetail).\n","format":"uri-reference"},"name":{"type":"string"}},"description":"A [schedule search](schedules#get-api-schedules) returns an array of these.  It is a\nsubset of what you get from a detail page at `/api/schedules/{id}` (linked as the href in this\nobject).\n"}}}}
```

## The ScheduleSummary object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ScheduleSummary":{"title":"Schedule summary","type":"object","properties":{"href":{"type":"string","description":"A link to a [schedule detail](models#scheduledetail).\n","format":"uri-reference"},"name":{"type":"string"}},"description":"A [schedule search](schedules#get-api-schedules) returns an array of these.  It is a\nsubset of what you get from a detail page at `/api/schedules/{id}` (linked as the href in this\nobject).\n"}}}}
```

## The ScheduleDetail object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"ScheduleDetail":{"title":"Schedule detail","description":"[/api/schedules/{id}](schedules#get-api-schedules-id-) returns one of these, and you put\n one of these in the body of a POST or PATCH to create or edit a schedule.\n","allOf":[{"$ref":"#/components/schemas/ScheduleSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"The division containing this schedule.  It is possible to change a schedule's\ndivision after creating it.\n"},"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"},"type":{"type":"object","properties":{"type":{"type":"string","enum":["accessZoneSchedule","accessSchedule","alarmZoneSchedule","outputSchedule","notificationSchedule","hVLFSchedule","elevatorKioskControlSchedule"]}},"description":"This block contains a string field `type` which will (in the server's response to a\nGET) or must (in the body of your POST) be one of the seven schedule types.  It is not a\nvalid field in a PATCH, because you cannot change the type of an existing schedule.\n\nElevator kiosk control schedules arrived in 8.60.\n"},"dayCategories":{"description":"This is the part of the schedule that controls when changes occur on its scheduled\nitems.\n\nIt is an array of objects, each containing a day category and an array of times.  The\nday category picks days of the year, and the `times` array sets what will happen and\nat what times on those days.\n\nIn the body of your POST:\n\n  * The `time` field of each object inside `times` must be a string of the form\n    `HH:MM` between 00:00 and 23:59.  If you find another format that works (four\n    zeroes, for example), it may not work in future versions.\n\n  * Each day category must have an entry at 00:00.  This means an item does not need\n    to search back in time to find what state it should be in when it first comes\n    online.\n\n  * Each day category cannot have more than one entry at the same time.\n\nIf you receive a 400 response to your POST or PATCH and one of those rules is the\ncause, the body of the response should contain a reminder.\n\nThe `state` field is an array describing what should happen at that time.  It is\ncomparable to the `statusFlags` arrays on access zones, alarm zones, outputs, and\nfence zones.  For most schedule types it will contain only one word, but the extra\nflag `usePin` may accompany access zone state changes.\n\nWhen building your JSON, treat these string comparisons as case-sensitive.\n\nAll schedule types can have a state change called 'cancelUntimedOverrides'.  That sets\nan item back to its scheduled state if it was under the effect of an override with no\nend time.\n\nOther than that, each schedule type has its own set of state changes:\n\n  * An Access Schedule, also known as a Cardholder Access Schedule, controls the\n    ability of the members of an access group to pass into an access zone.  The valid\n    states are `grant` and `deny`.  Note that 'deny' is a misnomer:  a cardholder will\n    gain access through a door if they are a member of a different access group that\n    still has access.\n\n  * An Access Zone Schedule controls the mode of an access zone.  The valid states are\n    the same as the [zone's status flags](models#accesszonedetail):  `secure`,\n    `dualAuth`, `codeOrCard`, or `free`.  The extra flag `usePin` means the same here\n    as it does in the status flags:  people will need their PINs at readers and alarm\n    terminals.\n\n  * An Alarm Zone Schedule switches an alarm zone between its four modes: `set`,\n    `unset`, `user1`, and `user2`.  Use the words `user1` and `user2` here even if you\n    have renamed them in the server properties.\n\n  * An Output Schedule can be `on` or `off`, plain and simple.\n\n  * A Notification Schedule controls when notifications go out.  They can make sure\n    that notifications go to the people who are on shift, and they can prevent\n    bothering people at night.  Like the access and output schedules it is binary, but\n    the valid states are called `notificationEnabled` and `notificationDisabled`.\n\n  * A HV/LF Schedule controls the voltage on an electric fence.  'lowFeel' mode allows\n    detection without the deterrent of `highVoltage`.\n\nThis example sets an access zone to secure mode between 7.30am and 6:00pm on work\ndays, and secure plus PIN mode at all other times.\n","type":"array","items":{"type":"object","properties":{"dayCategory":{"type":"object","properties":{"name":{"type":"string","readOnly":true},"href":{"type":"string","format":"uri-reference","description":"The API's identifier for an item."}}},"times":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","pattern":"^[012][0-9]:[0-6][0-9]$"},"state":{"type":"array","items":{"type":"string"}}}}}}}},"scheduledItems":{"readOnly":true,"description":"An array containing the names and hrefs of all the items that this schedule controls\nand that the operator has the privilege to view.\n\nThis is generated data.  A schedule resides in the configuration of the items that use\nit, rather than the other way around, so this block is a handy aggregation of the\ninverse of those relationships.  As such it is read-only:  the server will ignore it\nif you send it in a POST or a PATCH.\n","type":"array","items":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"}}}}}}]},"ScheduleSummary":{"title":"Schedule summary","type":"object","properties":{"href":{"type":"string","description":"A link to a [schedule detail](models#scheduledetail).\n","format":"uri-reference"},"name":{"type":"string"}},"description":"A [schedule search](schedules#get-api-schedules) returns an array of these.  It is a\nsubset of what you get from a detail page at `/api/schedules/{id}` (linked as the href in this\nobject).\n"}}}}
```

## The CardholderRedaction object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"CardholderRedaction":{"title":"Cardholder redaction","description":"These appear in an array in a cardholder object.  Each describes a redaction scheduled for the\ncardholder.\n\nA cardholder can have multiple event redactions pending, because they can operate on events\nfrom different periods, but since a cardholder redaction removes the cardholder item there\ncan be only one.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"DELETE this URL to cancel this redaction.\n\nDELETE is the only verb you can use on this URL.  GET will always return a 404.\n"},"type":{"type":"string","enum":["normalEvents","cardholder"],"description":"Whether this redaction is for cardholder events or cardholder information.\n"},"when":{"description":"When the redaction is meant to happen.  This should be in the future.  If it is in the past,\nthe service returns 400-Bad Request Invalid Start Time.\n\nOptional.  If it is absent, it means to do it asap.\n","type":"string","format":"date-time"},"before":{"description":"For event redactions, do not redact any events after this time.  No effect on cardholder\ninformation redactions.\n\nOptional.\n","type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","inProgress","cancelled","done","failed"],"description":"The status of this redaction.\n"},"redactionOperator":{"description":"A block containing the href and current name of the operator who scheduled the redaction.\n","type":"object"}}}}}}
```

## The Visit object

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"components":{"schemas":{"Visit":{"description":"`GET /api/visits` returns an array of these (with fewer fields) and `GET /api/visits/{id}` returns one.\n","properties":{"name":{"type":"string","description":"You can name a visit however you like.  Gallagher's in-house applications name them after\ntheir hosts.\n\nThis field is mandatory when creating a visit.  No blank names allowed!\n"},"href":{"type":"string","format":"uri-reference","description":"This is the URL to send a PATCH to when modifying an existing visit.  You can find it in\nthe body of a GET that returns a visit, or in the Location header of a POST that creates\none.\n\nIt is not necessary in a POST or PATCH.  The server will ignore it if you send it.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server.  This field is missing from items that are held on\nthe machine that served the API request.  Added in 8.40.\n\nThis is a read-only field.  The server will ignore it if you send it.\n"},"description":{"type":"string","description":"A visit's description is free text.  Gallagher's visitor management clients use it to\nstore the visit's purpose.  You can change it at any time.\n"},"division":{"type":"object","description":"The division containing this visit.\n\nIt will be the visit's reception's division, or if that division did not have an active\nvisitor management configuration when the visit was created, the first ancestor up the\ndivision tree that did.\n\nThe server will ignore it if you send it, because you cannot change a visit's division\ndirectly.  You can affect it indirectly by changing the visit's reception.\n"},"reception":{"type":"object","description":"Every visit must have a reception.  It represents the location at which your visitors will\nfirst arrive.  Having one attached to a visit allows a kiosk at that location to hide\nvisits for other receptions, revealing only those meant to start there.\n\nYour choice of reception also determines the rules with which the visit must comply, because\nthose rules come from the visitor management configuration on the reception's division.\n\nSince every visit must have a reception, every POST that creates a visit must have one.  Once\nyou have a visit in the system you can change its reception, but be aware that changing\nreceptions might change the visit's division, which also might change the rules to which the\nvisit must conform, and if any validation fails--and there is a lot of it--the PATCH will\nfail.\n\nThe reception's name comes from the server in a GET, but you need not send it when creating or\nmodifying a visit.  Command Centre only needs an href from you.\n\nNote that you must send the reception like it appears in the example, as an href inside a\nblock called `reception`.  This will not work:\n\n`\"reception\": \"https://localhost:8904/api/receptions/123\"`\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}},"visitorType":{"type":"object","description":"Every visit must also have a visitor type.  It provides an access group for your visitors\nso that they can have personal data (remember that a cardholder must be in an access group\nbefore he or she can have a PDF), and it is an index into the visitor management\nconfiguration that governs things like the host (the cardholder who is responsible for\nyour visitors) and the access groups that the server will give your visitors when they\nsign in.\n\nUse the href from the division's visitor management configuration, or the access group's\nhref.  Both will work.\n\nYou will receive the `accessGroup` object inside the `visitorType` block in a GET, but you\nneedn't send it in a POST or PATCH.  The server can find the visitor type using only its href.\n\nLike the reception, when you send this to the server you must use the same form as the\nexample, as an href inside a block called `visitorType`.  The href can be to an access group\nthat you got from an [access group](access-groups#get-api-access_groups) or the\n`visitorTypes` in the visitor management configuration on a\n[division](divisions#get-api-divisions-_operation_).  For example, both of these will\nwork as visitor type hrefs:\n\n`https://localhost:8904/api/access_groups/925` (taken from another visit, or a search of\naccess groups)\n\n`https://localhost:8904/api/divisions/2/visitor_types/925` (taken from a division config)\n\nYour operator must have the privilege to view the access group, otherwise you will be told\n'Access denied when writing to one or more fields'.  Having the 'Modify Access Control'\nprivilege on the group's division is a good choice because it not only gives you a view of\naccess groups but the ability to change cardholders' membership of them, which you need to add\nvisitors and visitor groups.\n","properties":{"href":{"type":"string","format":"uri-reference"},"accessGroup":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}}},"host":{"type":"object","description":"A host is a cardholder, and every visit has one.  A visit's host is the person who\n(optionally) receives an email or SMS notification when visitors start signing in, and is\nresponsible for them until they sign out again.\n\nA host must be a member of at least one of the visit's visitor type's host access groups\nat the time that you create or modify the visit.  To find out what those are, get the\nvisitor management configuration for your reception's division (remembering that your\nvisit's division is its reception's division).  That visitor type contains an array of\naccess groups called `hostAccessGroups`.  Your host cardholder must be a member of one of\nthose groups or their descendants.\n\nWhen you GET a visit the server will send you the host cardholder's name, but when you create\na visit with a POST or modify one with a PATCH, you needn't send the name back.  Do so if you\nmust, but it will not have an effect.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}},"from":{"type":"string","format":"date-time","description":"Every visit has a validity period, defined by start and end times called `from` and\n`until`.\n\nNot only are they both required when you create a visit, but the server will insist that\n`until` is later than `from` and that you followed [the date-time rules](#dates-and-times).\n\nYou can use short forms such as `2021-04-01+12` and the server will fill in zeroes for the\nparts you missed.  But because the end time must always be later than the start time you\ncannot use the same date for both start and end.  The server will treat them both like\nmidnight, see that they are equal, and reject your API call.  So if you have a one-day visit,\nbump `until` by a day or pad it out until the evening.  `2021-04-01T23:59:59+12`, for example.\n"},"until":{"type":"string","format":"date-time","description":"Every visit has a validity period, defined by start and end times called `from` and\n`until`.\n\nNot only are they both required when you create a visit, but the server will insist that\n`until` is later than `from` and that you followed [the date-time rules](#dates-and-times).\n\nYou can use short forms such as `2021-04-01+12` and the server will fill in zeroes for the\nparts you missed.  But because the end time must always be later than the start time you\ncannot use the same date for both start and end.  The server will treat them both like\nmidnight, see that they are equal, and reject your API call.  So if you have a one-day visit,\nbump `until` by a day or pad it out until the evening.  `2021-04-01T23:59:59+12`, for example.\n"},"location":{"type":"string","description":"Free text.  Entirely optional in the POST and PATCH."},"visitorAccessGroups":{"description":"These are the access groups that the server will add your visitors to after they complete\ninduction and sign in.  They define the access that your visitors have to the site, as\nthey do for all cardholders.\n\nIt is perfectly valid to have no visitor access groups on a visit - it just means that\nsomeone will be opening all your guests' doors for them.  That might be the kind of thing\nthey are used to anyway.\n\nThe visitor access groups on a visit must be a subset of the visitor access groups on the\ndivision's visitor type (in the list of visitor access groups in the visit's reception's\ndivision's visitor management configuration, in other words).\n\nWhen you send a visitor access group block to the server in a POST, just send an array of\nblocks each containing an href to an access group.  This is one reason why you cannot copy a\nvisit by POSTing back the JSON from a GET.\n\nWhen you send a visitor access group block in a PATCH to edit an existing visit, the server\nexpects it to contain one or two arrays called `add` and `remove`.  The `add` array should\ncontain access group hrefs, exactly as you would send when creating a visit.  The `remove`\narray can contain access group hrefs or the hrefs you received in the GET.  The PATCH example\nshows two hrefs trying to remove the same access group.\n\nYour operator must have a privilege on the groups' divisions that allows viewing the access\ngroups and adding and removing cardholders to and from them, otherwise you will be told\n'Access denied when writing to one or more fields'.  'Modify Access Control' is a good choice.\n","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}},"visitors":{"type":"array","description":"When the server sends this array to you, it contains two hrefs for each cardholder due to\narrive in this visit.  The first, outside the `cardholder` block, is the URL you\n[PATCH](visits#patch-api-visits-id-visitors-visitorId-) to change the state of their visit (new in\n8.90).  The one inside the `cardholder` block is simply an href to the cardholder item.  You\ncan use either href when removing visitors from a visit with a PATCH.\n\nThe `status` block contains two fields.  `value` is a human-readable description of their\nstate in the server's language.  `type` comes from a fixed enumeration.\n\nThe `invitation` string is opaque:  please do not interpret it.\n\nNote that a visit with no visitors on it will come out of the API but will not appear in\nGallagher's visitor management application.  Why clutter the screen if you're not expecting\nanybody, after all.\n\nWhen you send a visitor block to the server in a POST to create a visit, just send an array of\nblocks each containing an href to a cardholder.  You do not need to put the hrefs inside\n`cardholder` blocks, as the server sends to you, so this is the other reason you cannot copy a\nvisit by POSTing back the JSON from a GET.\n\nAlso do not bother sending a `status` block:  the server will ignore it and set all visitors\nto 'expected'.\n\nWhen you send a visitor block in a PATCH to edit an existing visit, the server expects it to\ncontain an array called `add`, an array called `remove`, or both.  The `add` array should contain\ncardholder hrefs, exactly as you would send when creating a visit.  The `remove` array should\ncontain either of the hrefs you received for the cardholder in the GET.  The PATCH example\nshows two hrefs removing the same cardholder.\n\nYour operator must have a privilege on the groups' divisions that allows viewing the access\ngroups and adding and removing cardholders to and from them, otherwise you will be told\n'Access denied when writing to one or more fields'.  'Modify Access Control' is a good choice.\n","items":{"type":"object","properties":{"cardholder":{"description":"A block containing the name and cardholder href of the visitor.\n","type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}},"href":{"type":"string","format":"uri-reference","description":"An href unique to the pairing of this cardholder and this visit.  You can PATCH it to\nchange the visitor's state.\n\nNew to 8.90.\n"},"invitation":{"type":"string","description":"A blob of text which, when encoded into a QR code and presented to a Gallagher Visitor\nManagement kiosk, allows the visitor to sign in.\n\nThis does not appear unless you ask for it using the `fields` query parameter.\nBecause it is inside the `visitors` block, name it `visitors.invitation` in the field list.\n"},"status":{"type":"object","description":"The cardholder's status on this visit, in human-readable and machine-readable forms.\n\nAlso new to 8.90.\n","properties":{"value":{"type":"string","description":"A human-readable version of the visitor's status, varying with the version of\nCommand Centre and the server's locale.\n"},"type":{"type":"string","description":"The visitor's current state taken from a fixed list of strings.  New visitors have a\nstarting state of 'expected'.\n","enum":["expected","signingIn","signedIn","onSite","expectedBack","departed","cancelled"]}}}}}}}}}}}
```


---

# 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/models.md?ask=<question>&goal=<user_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.