> 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/pdf-definitions.md).
# PDF Definitions
A Personal Data Field is an item that adds a custom value to a cardholder. Each PDF has a type (text, image, numeric, ...) and optional constraints on the values that it can hold. For example, text, email, and telephone number types can have a regular expression with which new values must match. A date can have a maximum and a minimum. Text PDFs can have a list of valid values, like an enumeration. Mobile numbers and email addresses have a flag indicating whether they are suitable to receive SMS and email notifications.
There is more configuration: image PDFs have a type and size, to which Command Centre will transcode incoming images. All PDFs have their own access level (hidden, read-only, or full access) that applies to operators in operator groups that do not expressly override it.
Importantly, PDFs are attached to access groups. A cardholder can have a value for a PDF only if he or she is a member of one of the PDF's access groups.
This API lets you see the definitions and configuration of all the personal data fields in the system.
API routes that allow creating, modifying, and deleting PDF definitions are in development.
### Use cases
#### Finding all a cardholder's PDF definitions
You can see all a cardholder's PDF *values* by looking in the `personalDataDefinitions` block of a cardholder. But that will only show you the PDFs that the cardholder currently has values for -- it will not show you the blanks. If you are writing an application that needs to find all the PDFs that a cardholder could carry, you will need this process.
Recall that a PDF is attached to an access group and appears on all direct and indirect members of that access group. To find a cardholder's PDFs, including those for which the cardholder has no value, you must find all the cardholder's groups, then find all the PDFs on those groups.
1. GET the cardholder's access groups from the cardholder's detail page, or the search page with `accessGroups` added to the query's `fields` parameter.
2. Iterate through the hrefs of those access groups, GETting each. That will return their detail pages.
3. For each access group detail page, record the names and hrefs from the `personalDataDefinitions` block and add the `parent.href` link to the list of groups to check (unless you have already seen it, of course).
Now you have the names and hrefs of all the PDFs that the cardholder can hold.
#### Finding a PDF's regular expression
1. `GET /api`
2. Follow the link at `features.personalDataFields.personalDataFields.href` ↪, adding a search term to the query to thin out the results. For example, add `name="PDF name"` to only return the PDF definitions with that name.
#### Setting a cardholder's PDF value
You do that by PATCHing a cardholder with a field named after the PDF following an '@'.
### Licensing
Reading PDF definitions is enabled by the RESTCardholders licence. Routes to creating, delete, or modify them are still coming to the API.
## Search PDF definitions
> This returns the PDF definitions you are privileged to view. You will need the 'View\
> Personal Data Definitions' privilege, or its 'Edit' equivalent, on a PDF's division in order\
> to see it.\
> \
> The result will contain no more than 100 or 1000 objects, depending on your version; you\
> should follow the \`next\` link, if it is present, to collect more. When you have loaded all\
> the PDF definitions there will no \`next\` link.\
> \
> \[Do not code this URL]\(forward-compatibility-hateoas) into your application. Take\
> it from the href in the \`features.personalDataFields.personalDataFields\` section of \`/api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PDF definitions","description":"\nA Personal Data Field is an item that adds a custom value to a cardholder. Each PDF has a type\n(text, image, numeric, ...) and optional constraints on the values that it can hold. For\nexample, text, email, and telephone number types can have a regular expression with\nwhich new values must match. A date can have a maximum and a minimum. Text PDFs can have a\nlist of valid values, like an enumeration. Mobile numbers and email addresses have a flag\nindicating whether they are suitable to receive SMS and email notifications.\n\nThere is more configuration: image PDFs have a type and size, to which Command Centre will\ntranscode incoming images. All PDFs have their own access level\n(hidden, read-only, or full access) that applies to operators in operator groups that do not\nexpressly override it.\n\nImportantly, PDFs are attached to access groups. A cardholder can have a value for a PDF only\nif he or she is a member of one of the PDF's access groups.\n\nThis API lets you see the definitions and configuration of all the personal data fields in the\nsystem.\n\nAPI routes that allow creating, modifying, and deleting PDF definitions are in development.\n\n## Use cases\n\n### Finding all a cardholder's PDF definitions\n\nYou can see all a cardholder's PDF *values* by looking in the `personalDataDefinitions` block of\na [cardholder](models#cardholderdetail). But that will only show you the PDFs that the\ncardholder currently has values for -- it will not show you the blanks. If you are writing an\napplication that needs to find all the PDFs that a cardholder could carry, you will need this\nprocess.\n\nRecall that a PDF is attached to an access group and appears on all direct and indirect members\nof that access group. To find a cardholder's PDFs, including those for which the cardholder has\nno value, you must find all the cardholder's groups, then find all the PDFs on those groups.\n\n1. GET the cardholder's access groups from the cardholder's detail page, or the search page\n with `accessGroups` added to the query's `fields` parameter.\n2. Iterate through the hrefs of those access groups, GETting each. That will return their\n detail pages.\n3. For each access group detail page, record the names and hrefs from the\n `personalDataDefinitions` block and add the `parent.href` link to the list of groups to check\n (unless you have already seen it, of course).\n\nNow you have the names and hrefs of all the PDFs that the cardholder can hold.\n\n### Finding a PDF's regular expression\n\n1. `GET /api`\n2. Follow the link at `features.personalDataFields.personalDataFields.href`\n [↪](pdf-definitions#get-api-personal_data_fields), adding a search term to the query to\n thin out the results. For example, add `name=\"PDF name\"` to only return the PDF definitions\n with that name.\n\n### Setting a cardholder's PDF value\n\nYou do that by [PATCHing a cardholder](models#cardholderpatch) with a field named\nafter the PDF following an '@'.\n\n## Licensing\n\nReading PDF definitions is enabled by the RESTCardholders licence. Routes to creating, delete,\nor modify them are still coming to 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"},"pdf_fields":{"name":"fields","in":"query","description":"Specifies the fields in the search results. The values you can list are the same in the\nsearch and details pages. Using it you can return everything on the search page that you\nwould find on the details page. Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not\ngiven the parameter at all. Add more after a comma.\n\nTreat the string matches as case-sensitive.\n","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["href","id","name","description","division","serverDisplayName","type","default","required","unique","sortPriority","accessGroups","regex","regexDescription","defaultAccess","operatorAccess","notificationDefault","defaults"]},"default":["defaults"]}},"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":{"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"}}}}},"paths":{"/api/personal_data_fields":{"get":{"tags":["PDF definitions"],"summary":"Search PDF definitions","description":"This returns the PDF definitions you are privileged to view. You will need the 'View\nPersonal Data Definitions' privilege, or its 'Edit' equivalent, on a PDF's division in order\nto see it.\n\nThe result will contain no more than 100 or 1000 objects, depending on your version; you\nshould follow the `next` link, if it is present, to collect more. When you have loaded all\nthe PDF definitions there will no `next` link.\n\n[Do not code this URL](forward-compatibility-hateoas) into your application. Take\nit from the href in the `features.personalDataFields.personalDataFields` section of `/api`.\n","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"$ref":"#/components/parameters/pdf_fields"},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDFDefinitionSearch"}}}},"403":{"description":"The site does not have the RESTCardholders or RESTEvents licence."}}}}}}
```
## Create
> Creates a new personal data definition.\
> \
> \[Do not code this URL]\(forward-compatibility-hateoas) into your application. Take\
> it from the \`href\` field in the \`features.personalDataFields.personalDataFields.href\` field\
> of \`GET /api\`.\
> \
> When successful it returns a location header containing the address of the new PDF.\
> \
> Note that you can only create one per POST.\
> \
> This call is still in development.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PDF definitions","description":"\nA Personal Data Field is an item that adds a custom value to a cardholder. Each PDF has a type\n(text, image, numeric, ...) and optional constraints on the values that it can hold. For\nexample, text, email, and telephone number types can have a regular expression with\nwhich new values must match. A date can have a maximum and a minimum. Text PDFs can have a\nlist of valid values, like an enumeration. Mobile numbers and email addresses have a flag\nindicating whether they are suitable to receive SMS and email notifications.\n\nThere is more configuration: image PDFs have a type and size, to which Command Centre will\ntranscode incoming images. All PDFs have their own access level\n(hidden, read-only, or full access) that applies to operators in operator groups that do not\nexpressly override it.\n\nImportantly, PDFs are attached to access groups. A cardholder can have a value for a PDF only\nif he or she is a member of one of the PDF's access groups.\n\nThis API lets you see the definitions and configuration of all the personal data fields in the\nsystem.\n\nAPI routes that allow creating, modifying, and deleting PDF definitions are in development.\n\n## Use cases\n\n### Finding all a cardholder's PDF definitions\n\nYou can see all a cardholder's PDF *values* by looking in the `personalDataDefinitions` block of\na [cardholder](models#cardholderdetail). But that will only show you the PDFs that the\ncardholder currently has values for -- it will not show you the blanks. If you are writing an\napplication that needs to find all the PDFs that a cardholder could carry, you will need this\nprocess.\n\nRecall that a PDF is attached to an access group and appears on all direct and indirect members\nof that access group. To find a cardholder's PDFs, including those for which the cardholder has\nno value, you must find all the cardholder's groups, then find all the PDFs on those groups.\n\n1. GET the cardholder's access groups from the cardholder's detail page, or the search page\n with `accessGroups` added to the query's `fields` parameter.\n2. Iterate through the hrefs of those access groups, GETting each. That will return their\n detail pages.\n3. For each access group detail page, record the names and hrefs from the\n `personalDataDefinitions` block and add the `parent.href` link to the list of groups to check\n (unless you have already seen it, of course).\n\nNow you have the names and hrefs of all the PDFs that the cardholder can hold.\n\n### Finding a PDF's regular expression\n\n1. `GET /api`\n2. Follow the link at `features.personalDataFields.personalDataFields.href`\n [↪](pdf-definitions#get-api-personal_data_fields), adding a search term to the query to\n thin out the results. For example, add `name=\"PDF name\"` to only return the PDF definitions\n with that name.\n\n### Setting a cardholder's PDF value\n\nYou do that by [PATCHing a cardholder](models#cardholderpatch) with a field named\nafter the PDF following an '@'.\n\n## Licensing\n\nReading PDF definitions is enabled by the RESTCardholders licence. Routes to creating, delete,\nor modify them are still coming to 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":{"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"}}}}},"paths":{"/api/personal_data_fields":{"post":{"tags":["PDF definitions"],"summary":"Create","description":"Creates a new personal data definition.\n\n[Do not code this URL](forward-compatibility-hateoas) into your application. Take\nit from the `href` field in the `features.personalDataFields.personalDataFields.href` field\nof `GET /api`.\n\nWhen successful it returns a location header containing the address of the new PDF.\n\nNote that you can only create one per POST.\n\nThis call is still in development.\n","requestBody":{"description":"This example shows the fields that you can set when creating a PDF.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDFDefinition"}}},"required":true},"responses":{"201":{"description":"Success.","headers":{"location":{"schema":{"type":"string","format":"uri-reference"},"description":"The href of the new PDF."}}},"400":{"description":"The body of the POST did not describe a valid PDF.\n\nIf you see 'Invalid Personal Data Field JSON object', the server could not parse the\nJSON in the body of your POST. Remember to quote all strings, especially those that\ncontain @ symbols.\n"},"403":{"description":"The operator does not have a privilege that allows creating PDFs or the server is not\nlicensed.\n"}}}}}}
```
## Get details of a PDF definition
> This returns details for a PDF definition. Follow the href in the\
> \[summary]\(models#pdfdefinition) to get here, rather than \[building it\
> yourself]\(forward-compatibility-hateoas).
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PDF definitions","description":"\nA Personal Data Field is an item that adds a custom value to a cardholder. Each PDF has a type\n(text, image, numeric, ...) and optional constraints on the values that it can hold. For\nexample, text, email, and telephone number types can have a regular expression with\nwhich new values must match. A date can have a maximum and a minimum. Text PDFs can have a\nlist of valid values, like an enumeration. Mobile numbers and email addresses have a flag\nindicating whether they are suitable to receive SMS and email notifications.\n\nThere is more configuration: image PDFs have a type and size, to which Command Centre will\ntranscode incoming images. All PDFs have their own access level\n(hidden, read-only, or full access) that applies to operators in operator groups that do not\nexpressly override it.\n\nImportantly, PDFs are attached to access groups. A cardholder can have a value for a PDF only\nif he or she is a member of one of the PDF's access groups.\n\nThis API lets you see the definitions and configuration of all the personal data fields in the\nsystem.\n\nAPI routes that allow creating, modifying, and deleting PDF definitions are in development.\n\n## Use cases\n\n### Finding all a cardholder's PDF definitions\n\nYou can see all a cardholder's PDF *values* by looking in the `personalDataDefinitions` block of\na [cardholder](models#cardholderdetail). But that will only show you the PDFs that the\ncardholder currently has values for -- it will not show you the blanks. If you are writing an\napplication that needs to find all the PDFs that a cardholder could carry, you will need this\nprocess.\n\nRecall that a PDF is attached to an access group and appears on all direct and indirect members\nof that access group. To find a cardholder's PDFs, including those for which the cardholder has\nno value, you must find all the cardholder's groups, then find all the PDFs on those groups.\n\n1. GET the cardholder's access groups from the cardholder's detail page, or the search page\n with `accessGroups` added to the query's `fields` parameter.\n2. Iterate through the hrefs of those access groups, GETting each. That will return their\n detail pages.\n3. For each access group detail page, record the names and hrefs from the\n `personalDataDefinitions` block and add the `parent.href` link to the list of groups to check\n (unless you have already seen it, of course).\n\nNow you have the names and hrefs of all the PDFs that the cardholder can hold.\n\n### Finding a PDF's regular expression\n\n1. `GET /api`\n2. Follow the link at `features.personalDataFields.personalDataFields.href`\n [↪](pdf-definitions#get-api-personal_data_fields), adding a search term to the query to\n thin out the results. For example, add `name=\"PDF name\"` to only return the PDF definitions\n with that name.\n\n### Setting a cardholder's PDF value\n\nYou do that by [PATCHing a cardholder](models#cardholderpatch) with a field named\nafter the PDF following an '@'.\n\n## Licensing\n\nReading PDF definitions is enabled by the RESTCardholders licence. Routes to creating, delete,\nor modify them are still coming to 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":{"pdf_fields":{"name":"fields","in":"query","description":"Specifies the fields in the search results. The values you can list are the same in the\nsearch and details pages. Using it you can return everything on the search page that you\nwould find on the details page. Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not\ngiven the parameter at all. Add more after a comma.\n\nTreat the string matches as case-sensitive.\n","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["href","id","name","description","division","serverDisplayName","type","default","required","unique","sortPriority","accessGroups","regex","regexDescription","defaultAccess","operatorAccess","notificationDefault","defaults"]},"default":["defaults"]}}},"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"}}}}},"paths":{"/api/personal_data_fields/{id}":{"get":{"tags":["PDF definitions"],"summary":"Get details of a PDF definition","description":"This returns details for a PDF definition. Follow the href in the\n[summary](models#pdfdefinition) to get here, rather than [building it\nyourself](forward-compatibility-hateoas).\n","parameters":[{"$ref":"#/components/parameters/pdf_fields"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDFDefinition"}}}},"403":{"description":"The site does not have the RESTCardholders or RESTEvents licence\n"},"404":{"description":"The operator does not have a privilege that allows viewing that PDF's definition ('View'\nor 'Edit Personal Data Definitions'), or the PDF's own access control is hiding it from\nthe operator.\n"}}}}}}
```
## Remove
> This call removes a PDF item from Command Centre. Follow the href in the\
> \[summary]\(models#pdfdefinition) to get here, rather than \[building it\
> yourself]\(forward-compatibility-hateoas).
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PDF definitions","description":"\nA Personal Data Field is an item that adds a custom value to a cardholder. Each PDF has a type\n(text, image, numeric, ...) and optional constraints on the values that it can hold. For\nexample, text, email, and telephone number types can have a regular expression with\nwhich new values must match. A date can have a maximum and a minimum. Text PDFs can have a\nlist of valid values, like an enumeration. Mobile numbers and email addresses have a flag\nindicating whether they are suitable to receive SMS and email notifications.\n\nThere is more configuration: image PDFs have a type and size, to which Command Centre will\ntranscode incoming images. All PDFs have their own access level\n(hidden, read-only, or full access) that applies to operators in operator groups that do not\nexpressly override it.\n\nImportantly, PDFs are attached to access groups. A cardholder can have a value for a PDF only\nif he or she is a member of one of the PDF's access groups.\n\nThis API lets you see the definitions and configuration of all the personal data fields in the\nsystem.\n\nAPI routes that allow creating, modifying, and deleting PDF definitions are in development.\n\n## Use cases\n\n### Finding all a cardholder's PDF definitions\n\nYou can see all a cardholder's PDF *values* by looking in the `personalDataDefinitions` block of\na [cardholder](models#cardholderdetail). But that will only show you the PDFs that the\ncardholder currently has values for -- it will not show you the blanks. If you are writing an\napplication that needs to find all the PDFs that a cardholder could carry, you will need this\nprocess.\n\nRecall that a PDF is attached to an access group and appears on all direct and indirect members\nof that access group. To find a cardholder's PDFs, including those for which the cardholder has\nno value, you must find all the cardholder's groups, then find all the PDFs on those groups.\n\n1. GET the cardholder's access groups from the cardholder's detail page, or the search page\n with `accessGroups` added to the query's `fields` parameter.\n2. Iterate through the hrefs of those access groups, GETting each. That will return their\n detail pages.\n3. For each access group detail page, record the names and hrefs from the\n `personalDataDefinitions` block and add the `parent.href` link to the list of groups to check\n (unless you have already seen it, of course).\n\nNow you have the names and hrefs of all the PDFs that the cardholder can hold.\n\n### Finding a PDF's regular expression\n\n1. `GET /api`\n2. Follow the link at `features.personalDataFields.personalDataFields.href`\n [↪](pdf-definitions#get-api-personal_data_fields), adding a search term to the query to\n thin out the results. For example, add `name=\"PDF name\"` to only return the PDF definitions\n with that name.\n\n### Setting a cardholder's PDF value\n\nYou do that by [PATCHing a cardholder](models#cardholderpatch) with a field named\nafter the PDF following an '@'.\n\n## Licensing\n\nReading PDF definitions is enabled by the RESTCardholders licence. Routes to creating, delete,\nor modify them are still coming to 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"}}},"paths":{"/api/personal_data_fields/{id}":{"delete":{"tags":["PDF definitions"],"summary":"Remove","description":"This call removes a PDF item from Command Centre. Follow the href in the\n[summary](models#pdfdefinition) to get here, rather than [building it\nyourself](forward-compatibility-hateoas).\n","responses":{"200":{"description":"Success."},"204":{"description":"Success."},"400":{"description":"Deleting failed. This happens when the PDF is in use.\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 PDF, or the operator is not privileged to view it.\n"}}}}}}
```
## Update
> This is the call you use to update a PDF. Follow the href in the\
> \[summary]\(models#pdfdefinition) to get here, rather than \[building it\
> yourself]\(forward-compatibility-hateoas).\
> \
> The PATCH expects a document in the same format as the \[PDF\
> detail]\(models#pdfdefinition).\
> \
> This route is still in development.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PDF definitions","description":"\nA Personal Data Field is an item that adds a custom value to a cardholder. Each PDF has a type\n(text, image, numeric, ...) and optional constraints on the values that it can hold. For\nexample, text, email, and telephone number types can have a regular expression with\nwhich new values must match. A date can have a maximum and a minimum. Text PDFs can have a\nlist of valid values, like an enumeration. Mobile numbers and email addresses have a flag\nindicating whether they are suitable to receive SMS and email notifications.\n\nThere is more configuration: image PDFs have a type and size, to which Command Centre will\ntranscode incoming images. All PDFs have their own access level\n(hidden, read-only, or full access) that applies to operators in operator groups that do not\nexpressly override it.\n\nImportantly, PDFs are attached to access groups. A cardholder can have a value for a PDF only\nif he or she is a member of one of the PDF's access groups.\n\nThis API lets you see the definitions and configuration of all the personal data fields in the\nsystem.\n\nAPI routes that allow creating, modifying, and deleting PDF definitions are in development.\n\n## Use cases\n\n### Finding all a cardholder's PDF definitions\n\nYou can see all a cardholder's PDF *values* by looking in the `personalDataDefinitions` block of\na [cardholder](models#cardholderdetail). But that will only show you the PDFs that the\ncardholder currently has values for -- it will not show you the blanks. If you are writing an\napplication that needs to find all the PDFs that a cardholder could carry, you will need this\nprocess.\n\nRecall that a PDF is attached to an access group and appears on all direct and indirect members\nof that access group. To find a cardholder's PDFs, including those for which the cardholder has\nno value, you must find all the cardholder's groups, then find all the PDFs on those groups.\n\n1. GET the cardholder's access groups from the cardholder's detail page, or the search page\n with `accessGroups` added to the query's `fields` parameter.\n2. Iterate through the hrefs of those access groups, GETting each. That will return their\n detail pages.\n3. For each access group detail page, record the names and hrefs from the\n `personalDataDefinitions` block and add the `parent.href` link to the list of groups to check\n (unless you have already seen it, of course).\n\nNow you have the names and hrefs of all the PDFs that the cardholder can hold.\n\n### Finding a PDF's regular expression\n\n1. `GET /api`\n2. Follow the link at `features.personalDataFields.personalDataFields.href`\n [↪](pdf-definitions#get-api-personal_data_fields), adding a search term to the query to\n thin out the results. For example, add `name=\"PDF name\"` to only return the PDF definitions\n with that name.\n\n### Setting a cardholder's PDF value\n\nYou do that by [PATCHing a cardholder](models#cardholderpatch) with a field named\nafter the PDF following an '@'.\n\n## Licensing\n\nReading PDF definitions is enabled by the RESTCardholders licence. Routes to creating, delete,\nor modify them are still coming to 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":{"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"}}}}},"paths":{"/api/personal_data_fields/{id}":{"patch":{"tags":["PDF definitions"],"summary":"Update","description":"This is the call you use to update a PDF. Follow the href in the\n[summary](models#pdfdefinition) to get here, rather than [building it\nyourself](forward-compatibility-hateoas).\n\nThe PATCH expects a document in the same format as the [PDF\ndetail](models#pdfdefinition).\n\nThis route is still in development.\n","requestBody":{"description":"There are no mandatory fields when PATCHing. There are, however, some fields you cannot\nchange.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDFDefinition"}}},"required":true},"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 PDF. PDFs have many rules, easily\nenforced in a graphical interface but less so in an API. See the body of the response\nfor help on what went wrong.\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 'Edit Personal Data Definitions' privilege on the item you are changing,\nwhich means you need on it on its current division. You also need it on the new\ndivision, if you are changing that.\n"},"404":{"description":"That is not the URL of a PDF 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](pdf-definitions#get-api-personal_data_fields).\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/pdf-definitions.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.