> 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/competencies.md).
# Competencies
Competencies are items to which cardholders can be linked, and which access zones may require on a cardholder before allowing them in.
They have their own access privileges, so operators can see or edit a cardholder's competencies based on the competency's settings as well as the cardholder's division and the privileges the operator has in that division.
Notification settings on the competency cause advance warnings to go to the cardholder and his or her related cardholders (line managers, for example) before the competency expires.
Competencies differ from access groups in that a cardholder can have only one link to a given competency. Attempting to create another will either fail or raise a stateful alarm depending on your version of Command Centre.
The REST API gives you access to competencies through create, search, dereference, update, and delete functions described below.
The Configuration Client online help describes competencies fully.
### Licensing
Reading competencies is enabled by the RESTCardholders licence. Routes to create, delete, or modify them are not yet in the API.
## Search competencies
> This returns competencies matching your search criteria.\
> \
> The result will contain no more than 100 or 1000 competencies depending on your version; you\
> should follow the \`next\` link (if present) for the next batch.\
> \
> If your result set is empty it means your operator does not have the privilege to view any\
> competencies. Perhaps there are none in the divisions in which your operator has 'View\
> site' or 'Edit site', or your operator has no privileges at all.\
> \
> A bug in 7.90 meant that this call did not provide \`next\` links for sites that had more than\
> 100 competencies. If this is you, set the 'top' parameter as high as you can (as\
> recommended in the efficiency tips). Command Centre clamps that to a maximum of ten\
> thousand. If that is not enough competencies for you, you are probably already in contact\
> with Gallagher technical support.\
> \
> Get this URL from \`features.competencies.competencies.href\` in \`/api\`. In the interest of\
> forward compability, \[do not build it yourself]\(forward-compatibility-hateoas).
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Competencies","description":"Competencies are items to which cardholders can be linked, and which access zones may require on\na cardholder before allowing them in.\n\nThey have their own access privileges, so operators can see or edit a cardholder's competencies\nbased on the competency's settings as well as the cardholder's division and the privileges the\noperator has in that division.\n\nNotification settings on the competency cause advance warnings to go to the cardholder and his\nor her related cardholders (line managers, for example) before the competency expires.\n\nCompetencies differ from access groups in that a cardholder can have only one link to a given\ncompetency. Attempting to create another will either fail or raise a stateful alarm depending\non your version of Command Centre.\n\nThe REST API gives you access to competencies through create, search, dereference, update, and\ndelete functions described below.\n\nThe Configuration Client online help describes competencies fully.\n\n## Licensing\n\nReading competencies is enabled by the RESTCardholders licence. Routes to create, delete, or\nmodify them are not yet in the API.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","-id","-name"]},"required":false,"description":"Changes the sort field between database ID and name.\n\nIf you prefix `id` or `name` with a minus sign (ASCII 45), the sort order is reversed.\n\nThere are two very strong reasons to sort by ID:\n\n1. Sorting by name carries a risk of missing or duplicating objects if your result set spans\n multiple pages and another operator is editing the database while your REST client is\n enumerating them. This is known as \"page drift.\" Sorting by ID does not carry that risk.\n2. Following a `next` link is _dramatically_ quicker when sorting by ID.\n\nWe _strongly_ recommend sorting by ID. In case you were still in doubt, we will do that by\ndefault in a future version of Command Centre.\n\nThe server silently ignores anything except the options listed here.\n"},"top":{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Limits the results to no more than this many items per page.\n\nOlder versions of Command Centre returned 100 items per page in the absence of this parameter. That is acceptable for GUI\napplications that will only display the first page, but for integrations that intend to\nproceed through the entire database it causes a lot of chatter.\n\n8.70 and later versions will default to 1000 items per request. This is about where a graph\nof throughput versus page size begins to level out.\n"},"name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Limits the returned items to those with a name that matches this string. Without surrounding\nquotes or a percent sign or underscore, it is a substring match; surround the parameter with\ndouble quotes `\"...\"` for an exact match. Without quotes, a percent sign `%` will match any\nsubstring and an underscore will match any single character.\n\nThe search is always case-insensitive. Results are undefined if you do a substring search for\nthe empty string (`name=`). You will receive no items if you search for those with no name\n(`name=\"\"`), as all items must have a name.\n\nSearch parameters are ANDed together.\n"},"division":{"name":"division","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Limits the returned items to those that are in these divisions.\n\nThat includes all the items in those divisions' child divisions, because Command Centre treats\nitems as though they are also in their division's parent, and its parent, and so on up to the\nroot division.\n\nSeparate the IDs of the divisions in you are interested with commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n"},"directDivision":{"name":"directDivision","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Restricts items to those whose division is in this list.\n\nUnlike `division=`, it does not follow ancestry. That means it will limit the search to items\nthat are directly assigned to the divisions you list, whereas `division` (without the\n`direct`) will also include items that are assigned to their descendants.\n\nList the IDs of the divisions you are interested in separated by commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nBecause this is the first query parameter we added that contains a capital letter, this will\nbe the first time you have had to think about case sensitivity. `directDivision` works,\n`directdivision` does not.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n\nAdded in 9.20.\n"},"description":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Limits the returned items to those with a description that matches this string. By default it\nis a substring match; surround it with double quotes `\"...\"` for an exact match. A `_` will\nmatch any single character, and a `%` will match any substring. With or without quotes,\nhaving either of these wildcards in the string will anchor it at both ends as though you had\nsurrounded it with `\"`.\n\nThe search is always case-insensitive. Results are undefined if you search for the empty\nstring (`description=` or `description=\"\"`).\n\nSearch parameters are ANDed together.\n"},"pos":{"name":"pos","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. You may see it in URLs you receive from the server, but you must never add it yourself."},"skip":{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. Do not add it to your queries."}},"schemas":{"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"}}}}},"paths":{"/api/competencies":{"get":{"tags":["Competencies"],"summary":"Search competencies","description":"This returns competencies matching your search criteria.\n\nThe result will contain no more than 100 or 1000 competencies depending on your version; you\nshould follow the `next` link (if present) for the next batch.\n\nIf your result set is empty it means your operator does not have the privilege to view any\ncompetencies. Perhaps there are none in the divisions in which your operator has 'View\nsite' or 'Edit site', or your operator has no privileges at all.\n\nA bug in 7.90 meant that this call did not provide `next` links for sites that had more than\n100 competencies. If this is you, set the 'top' parameter as high as you can (as\nrecommended in the efficiency tips). Command Centre clamps that to a maximum of ten\nthousand. If that is not enough competencies for you, you are probably already in contact\nwith Gallagher technical support.\n\nGet this URL from `features.competencies.competencies.href` in `/api`. In the interest of\nforward compability, [do not build it yourself](forward-compatibility-hateoas).","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"name":"fields","in":"query","schema":{"type":"array","default":["defaults"],"items":{"type":"string","enum":["href","id","name","shortName","description","division","notes","expiryNotify","noticePeriod","defaultExpiry","defaultAccess","defaults"]}},"description":"Specifies which fields to return in the search results. The values you can list are the\nsame as the field names in the [details page](models#competencydetail). Using it\nyou can return everything on the search page that you would find on the details page.\nSeparate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not\ngiven the parameter at all. Add more after a comma.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them. In\n8.10 you will not. If you are going to send the fields parameter and need the href or ID,\nbe explicit.\n"},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success. See the note in the description about privileges if your result set is empty.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetencySearch"}}}},"403":{"description":"The installation lacks a cardholders licence."}}}}}}
```
## Create a competency
> Creates a new competency.\
> \
> The POST expects a document in the same format as the \[competency\
> detail]\(models#competency) but with far fewer fields. An example is \[this POST\
> example]\(models#competencypatchandpostexample).\
> \
> When successful it returns a \`location\` header containing the address of the new competency.\
> \
> Note that you can only create one competency per POST.\
> \
> \[Do not code this URL]\(forward-compatibility-hateoas) into your application. Take\
> it from the results of \`GET /api\`.\
> \
> This call is not yet in the API.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Competencies","description":"Competencies are items to which cardholders can be linked, and which access zones may require on\na cardholder before allowing them in.\n\nThey have their own access privileges, so operators can see or edit a cardholder's competencies\nbased on the competency's settings as well as the cardholder's division and the privileges the\noperator has in that division.\n\nNotification settings on the competency cause advance warnings to go to the cardholder and his\nor her related cardholders (line managers, for example) before the competency expires.\n\nCompetencies differ from access groups in that a cardholder can have only one link to a given\ncompetency. Attempting to create another will either fail or raise a stateful alarm depending\non your version of Command Centre.\n\nThe REST API gives you access to competencies through create, search, dereference, update, and\ndelete functions described below.\n\nThe Configuration Client online help describes competencies fully.\n\n## Licensing\n\nReading competencies is enabled by the RESTCardholders licence. Routes to create, delete, or\nmodify them are not yet in the API.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"requestBodies":{"CompetencyPATCHandPOSTExample":{"description":"This is an example of a PATCH you could use to update a competency, and a POST you could use\nto create one.\n\nNo fields are mandatory in a PATCH, but when using a POST to create a competency you must\nsupply a division.\n","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new item's name. If you supply a name and another item of the same type\nalready exists with that name, the call will fail. If you leave it blank in a\nPOST, Command Centre will pick a name for you.\n"},"shortName":{"type":"string","maxLength":16,"description":"If you supply a string that is too long, Command Centre will truncate it.\n"},"description":{"type":"string","description":"The new item's description."},"division":{"type":"object","description":"The division to contain this competency.\n\nMandatory when creating a new competency.\n"},"notes":{"type":"string","description":"A string, able to be much longer than `description`, suitable for holding notes\nabout the item.\n"}}}}}}}},"paths":{"/api/competencies":{"post":{"tags":["Competencies"],"summary":"Create a competency","description":"Creates a new competency.\n\nThe POST expects a document in the same format as the [competency\ndetail](models#competency) but with far fewer fields. An example is [this POST\nexample](models#competencypatchandpostexample).\n\nWhen successful it returns a `location` header containing the address of the new competency.\n\nNote that you can only create one competency per POST.\n\n[Do not code this URL](forward-compatibility-hateoas) into your application. Take\nit from the results of `GET /api`.\n\nThis call is not yet in the API.\n","requestBody":{"$ref":"#/components/requestBodies/CompetencyPATCHandPOSTExample"},"responses":{"201":{"description":"Success. Check the response body for feedback about your request.\n","headers":{"location":{"description":"The href of the new competency.","schema":{"type":"string","format":"uri-reference"}}}},"400":{"description":"The body of the POST did not describe a valid competency. You may have tried to give\nthe new competency the same name as an existing one.\n\nSee the body of the response for help.\n"},"403":{"description":"The operator does not have a privilege on the division that allows creating items inside\nit ('Configure Site'), or the server has reached its licensed limit of competencies.\n"}}}}}}
```
## Get details of a competency
> You get this URL from a cardholder or from a competency search. In the interest of forward\
> compability, \[do not build it yourself]\(forward-compatibility-hateoas).\
> \
> The results document gives everything Command Centre has on a competency except the warning\
> messages that appear on a reader when a cardholder needs to take action.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Competencies","description":"Competencies are items to which cardholders can be linked, and which access zones may require on\na cardholder before allowing them in.\n\nThey have their own access privileges, so operators can see or edit a cardholder's competencies\nbased on the competency's settings as well as the cardholder's division and the privileges the\noperator has in that division.\n\nNotification settings on the competency cause advance warnings to go to the cardholder and his\nor her related cardholders (line managers, for example) before the competency expires.\n\nCompetencies differ from access groups in that a cardholder can have only one link to a given\ncompetency. Attempting to create another will either fail or raise a stateful alarm depending\non your version of Command Centre.\n\nThe REST API gives you access to competencies through create, search, dereference, update, and\ndelete functions described below.\n\nThe Configuration Client online help describes competencies fully.\n\n## Licensing\n\nReading competencies is enabled by the RESTCardholders licence. Routes to create, delete, or\nmodify them are not yet in the API.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"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"}}}}},"paths":{"/api/competencies/{id}":{"get":{"tags":["Competencies"],"summary":"Get details of a competency","description":"You get this URL from a cardholder or from a competency search. In the interest of forward\ncompability, [do not build it yourself](forward-compatibility-hateoas).\n\nThe results document gives everything Command Centre has on a competency except the warning\nmessages that appear on a reader when a cardholder needs to take action.","parameters":[{"name":"fields","in":"query","required":false,"schema":{"default":["defaults"],"type":"array","items":{"type":"string","enum":["href","id","name","shortName","description","division","notes","expiryNotify","noticePeriod","defaultExpiry","defaultAccess","defaults"]}},"description":"Specifies which fields to return. The values you can list are the same as the field names\nin the [details page](models#competencydetail). Use it to reduce the size of the\nresult document. Separate values with commas.\n\nTreat the string matches as case-sensitive.\n"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetencyDetail"}}}},"403":{"description":"The installation lacks a cardholders licence."},"404":{"description":"Your REST operator does not have the privilege to view this competency.\n"}}}}}}
```
## Remove a competency
> This call removes a competency from Command Centre. You get this URL from a cardholder or\
> from a competency search. In the interest of forward compability, \[do not build it\
> yourself]\(forward-compatibility-hateoas).\
> \
> This call is not yet in the API.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Competencies","description":"Competencies are items to which cardholders can be linked, and which access zones may require on\na cardholder before allowing them in.\n\nThey have their own access privileges, so operators can see or edit a cardholder's competencies\nbased on the competency's settings as well as the cardholder's division and the privileges the\noperator has in that division.\n\nNotification settings on the competency cause advance warnings to go to the cardholder and his\nor her related cardholders (line managers, for example) before the competency expires.\n\nCompetencies differ from access groups in that a cardholder can have only one link to a given\ncompetency. Attempting to create another will either fail or raise a stateful alarm depending\non your version of Command Centre.\n\nThe REST API gives you access to competencies through create, search, dereference, update, and\ndelete functions described below.\n\nThe Configuration Client online help describes competencies fully.\n\n## Licensing\n\nReading competencies is enabled by the RESTCardholders licence. Routes to create, delete, or\nmodify them are not yet in the API.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."}}},"paths":{"/api/competencies/{id}":{"delete":{"tags":["Competencies"],"summary":"Remove a competency","description":"This call removes a competency from Command Centre. You get this URL from a cardholder or\nfrom a competency search. In the interest of forward compability, [do not build it\nyourself](forward-compatibility-hateoas).\n\nThis call is not yet in the API.\n","parameters":[{"$ref":"#/components/parameters/id"}],"responses":{"200":{"description":"Success."},"204":{"description":"Success."},"400":{"description":"Deleting the competency failed. This happens when it is associated with a cardholder -\neven if it is inactive.\n"},"403":{"description":"The operator has the permission to view the item but not delete it.\n"},"404":{"description":"That is not the URL of a competency, or the operator is not privileged to view it.\n"}}}}}}
```
## Update a competency
> This is the call you use to update a competency's name, short name, description, notes, or\
> division. In the interest of forward compability, take the URL from the results of a\
> competency search rather than \[building it yourself]\(forward-compatibility-hateoas).\
> \
> The PATCH expects a document in the same format as the \[competency\
> detail]\(models#competencydetail) but with fewer fields. An example is \[this PATCH\
> example]\(models#competencypatchandpostexample).\
> \
> This call is not yet in the API.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Competencies","description":"Competencies are items to which cardholders can be linked, and which access zones may require on\na cardholder before allowing them in.\n\nThey have their own access privileges, so operators can see or edit a cardholder's competencies\nbased on the competency's settings as well as the cardholder's division and the privileges the\noperator has in that division.\n\nNotification settings on the competency cause advance warnings to go to the cardholder and his\nor her related cardholders (line managers, for example) before the competency expires.\n\nCompetencies differ from access groups in that a cardholder can have only one link to a given\ncompetency. Attempting to create another will either fail or raise a stateful alarm depending\non your version of Command Centre.\n\nThe REST API gives you access to competencies through create, search, dereference, update, and\ndelete functions described below.\n\nThe Configuration Client online help describes competencies fully.\n\n## Licensing\n\nReading competencies is enabled by the RESTCardholders licence. Routes to create, delete, or\nmodify them are not yet in the API.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"requestBodies":{"CompetencyPATCHandPOSTExample":{"description":"This is an example of a PATCH you could use to update a competency, and a POST you could use\nto create one.\n\nNo fields are mandatory in a PATCH, but when using a POST to create a competency you must\nsupply a division.\n","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new item's name. If you supply a name and another item of the same type\nalready exists with that name, the call will fail. If you leave it blank in a\nPOST, Command Centre will pick a name for you.\n"},"shortName":{"type":"string","maxLength":16,"description":"If you supply a string that is too long, Command Centre will truncate it.\n"},"description":{"type":"string","description":"The new item's description."},"division":{"type":"object","description":"The division to contain this competency.\n\nMandatory when creating a new competency.\n"},"notes":{"type":"string","description":"A string, able to be much longer than `description`, suitable for holding notes\nabout the item.\n"}}}}}}}},"paths":{"/api/competencies/{id}":{"patch":{"tags":["Competencies"],"summary":"Update a competency","description":"This is the call you use to update a competency's name, short name, description, notes, or\ndivision. In the interest of forward compability, take the URL from the results of a\ncompetency search rather than [building it yourself](forward-compatibility-hateoas).\n\nThe PATCH expects a document in the same format as the [competency\ndetail](models#competencydetail) but with fewer fields. An example is [this PATCH\nexample](models#competencypatchandpostexample).\n\nThis call is not yet in the API.\n","requestBody":{"$ref":"#/components/requestBodies/CompetencyPATCHandPOSTExample"},"responses":{"200":{"description":"Success. Future versions will return feedback from the server about your PATCH.\n"},"204":{"description":"Success."},"400":{"description":"The body of the PATCH did not describe a valid competency. See the body of the response\nfor help on what went wrong. It may be that you tried to use the name of another\ncompetency: no two items of the same type can have the same name. Or you may have\ntried to set the competency's division to one that is not visible to you.\n"},"403":{"description":"The operator has a privilege that allows viewing the item but not modifying it, or you\ntried to set the division to one you cannot configure, or the server is missing the\nnecessary licence.\n\nYou need the 'Configure Site' privilege on the item you are changing, which means you need\non it on the item's current division. You also need it on the new division, if you are\nchanging that.\n"},"404":{"description":"That is not the URL of a competency or your operator does not have the privilege to view\nit. This probably means you have built the URL yourself instead of taking it from the\nresults of a [GET](competencies#get-api-competencies).\n"},"409":{"description":"The item is locked for editing by another operator. The body of the response will\ntell you which operator is holding the lock.\n"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.security.gallagher.com/knowledge-hub/developer/rest-api/competencies.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.