> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/api-reference/dictionaries.md).

# Dictionaries

APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated.

## Get all Dictionary Formations

> Get all dictionary formations.\
> \
> \### HTTP Request\
> \
> \*\*\*GET\*\*\* \`/{tenantName}/{instanceName}/formations/{version}/dictionaries\`\
> \
> in our example it would be:\
> \
> \*\*\*GET\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/formations/current/dictionaries\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 200 | OK |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"Dictionary":{"type":"object","required":["name","fields"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9\\-_]+$"},"title":{"type":"string"},"internal":{"type":"boolean","readOnly":true},"fields":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryField"}}}},"DictionaryField":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9\\-_]+$"},"type":{"$ref":"#/components/schemas/FieldTypeEnum"}}},"FieldTypeEnum":{"type":"string","enum":["TEXT","TEXTAREA","PASSWORD","EMAIL","INTEGER","FLOAT","PERCENT","RADIO","CHECKBOX","SELECT","CHOICE","DATE","TIME","DATETIME","FILE","IMAGE","URL","PHONE","UUID","SSN","ADDRESS","LOCATION","FORMULA","OBJECT","SIGNATURE"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/formations/current/dictionaries":{"get":{"summary":"Get all Dictionary Formations","tags":["Dictionaries"],"operationId":"Get_all_Dictionary_Formations","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"excludeInternal","in":"query","required":false,"schema":{"type":"boolean"},"description":"true/false"}],"responses":{"200":{"description":"List of dictionary formations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Dictionary"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Get all dictionary formations.\n\n### HTTP Request\n\n***GET*** `/{tenantName}/{instanceName}/formations/{version}/dictionaries`\n\nin our example it would be:\n\n***GET*** `https://api.live.welkincloud.io/gh/sb-demo/formations/current/dictionaries`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 200 | OK |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |"}}}}
```

## Get Dictionary Formation by name

> \### HTTP Request\
> \
> \_\*\*GET\*\*\_ \`/{tenantName}/{instanceName}/formations/{version}/dictionaries/{dictionaryName}\`\
> \
> in our example it would be:\
> \
> \_\*\*GET\*\*\_ \`<https://api.live.welkincloud.io/gh/sb-demo/formations/current/dictionaries/timezone\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 200 | OK |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"Dictionary":{"type":"object","required":["name","fields"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9\\-_]+$"},"title":{"type":"string"},"internal":{"type":"boolean","readOnly":true},"fields":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryField"}}}},"DictionaryField":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9\\-_]+$"},"type":{"$ref":"#/components/schemas/FieldTypeEnum"}}},"FieldTypeEnum":{"type":"string","enum":["TEXT","TEXTAREA","PASSWORD","EMAIL","INTEGER","FLOAT","PERCENT","RADIO","CHECKBOX","SELECT","CHOICE","DATE","TIME","DATETIME","FILE","IMAGE","URL","PHONE","UUID","SSN","ADDRESS","LOCATION","FORMULA","OBJECT","SIGNATURE"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/formations/current/dictionaries/{dictionaryName}":{"get":{"summary":"Get Dictionary Formation by name","tags":["Dictionaries"],"operationId":"Get_Dictionary_Formation_by_name","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"}],"responses":{"200":{"description":"Dictionary formation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dictionary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"### HTTP Request\n\n_**GET**_ `/{tenantName}/{instanceName}/formations/{version}/dictionaries/{dictionaryName}`\n\nin our example it would be:\n\n_**GET**_ `https://api.live.welkincloud.io/gh/sb-demo/formations/current/dictionaries/timezone`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 200 | OK |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |"}}}}
```

## Get Dictionary Record by name and ID

> \### HTTP Request\
> \
> \*\*\*GET\*\*\* \`/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}\`\
> \
> in our example it would be:\
> \
> \*\*\*GET\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt/001806e2-3464-40b2-8adb-e756abe31fb1\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 200 | OK |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"DictionaryRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"fullValue":{"type":"string","nullable":true},"deleted":{"type":"boolean"},"values":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}":{"get":{"summary":"Get Dictionary Record by name and ID","tags":["Dictionaries"],"operationId":"Get_Dictionary_Record_by_name_and_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"},{"name":"dictionaryRecordId","in":"path","required":true,"description":"`dictionaryRecordId` path parameter","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dictionary record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecord"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"### HTTP Request\n\n***GET*** `/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}`\n\nin our example it would be:\n\n***GET*** `https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt/001806e2-3464-40b2-8adb-e756abe31fb1`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 200 | OK |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |"}}}}
```

## Update Dictionary Record by name and ID

> \### HTTP Request\
> \
> \*\*\*PUT\*\*\* \`/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}\`\
> \
> in our example it would be:\
> \
> \*\*\*PUT\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt/001806e2-3464-40b2-8adb-e756abe31fb1\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 200 | OK |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"DictionaryRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"fullValue":{"type":"string","nullable":true},"deleted":{"type":"boolean"},"values":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}":{"put":{"summary":"Update Dictionary Record by name and ID","tags":["Dictionaries"],"operationId":"Update_Dictionary_Record_by_name_and_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"},{"name":"dictionaryRecordId","in":"path","required":true,"description":"`dictionaryRecordId` path parameter","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Updated dictionary record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecord"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"### HTTP Request\n\n***PUT*** `/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}`\n\nin our example it would be:\n\n***PUT*** `https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt/001806e2-3464-40b2-8adb-e756abe31fb1`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 200 | OK |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecord"}}}}}}}}
```

## Delete Dictionary Record by name and ID

> \### HTTP Request\
> \
> \*\*\*DELETE\*\*\* \`/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}\`\
> \
> in our example it would be:\
> \
> \*\*\*DELETE\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt/001806e2-3464-40b2-8adb-e756abe31fb1\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 200 | OK |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"DictionaryRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"fullValue":{"type":"string","nullable":true},"deleted":{"type":"boolean"},"values":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}":{"delete":{"summary":"Delete Dictionary Record by name and ID","tags":["Dictionaries"],"operationId":"Delete_Dictionary_Record_by_name_and_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"},{"name":"dictionaryRecordId","in":"path","required":true,"description":"`dictionaryRecordId` path parameter","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dictionary record deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecord"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"### HTTP Request\n\n***DELETE*** `/{tenantName}/{instanceName}/dictionaries/{dictionaryName}/{dictionaryRecordId}`\n\nin our example it would be:\n\n***DELETE*** `https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt/001806e2-3464-40b2-8adb-e756abe31fb1`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 200 | OK |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |"}}}}
```

## Get all Dictionary Records by name

> \### HTTP Request\
> \
> \*\*\*GET\*\*\* \`/{tenantName}/{instanceName}/dictionaries/{dictionaryName}\`\
> \
> in our example it would be:\
> \
> \*\*\*GET\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 200 | OK |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"DictionaryRecordBatch":{"type":"object","properties":{"dictionaryName":{"type":"string","readOnly":true},"lastUpdatedAt":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"records":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryRecord"}}}},"DictionaryRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"fullValue":{"type":"string","nullable":true},"deleted":{"type":"boolean"},"values":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/dictionaries/{dictionaryName}":{"get":{"summary":"Get all Dictionary Records by name","tags":["Dictionaries"],"operationId":"Get_all_Dictionary_Records_by_name","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"dateStart","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"dateEnd","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"showDeleted","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"All dictionary records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecordBatch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"### HTTP Request\n\n***GET*** `/{tenantName}/{instanceName}/dictionaries/{dictionaryName}`\n\nin our example it would be:\n\n***GET*** `https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 200 | OK |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |"}}}}
```

## Add value to Dictionary

> \### HTTP Request\
> \
> \*\*\*POST\*\*\* \`/{tenantName}/{instanceName}/dictionaries/{dictionaryName}\`\
> \
> in our example it would be:\
> \
> \*\*\*POST\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 201 | Created |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"DictionaryRecordBatch":{"type":"object","properties":{"dictionaryName":{"type":"string","readOnly":true},"lastUpdatedAt":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"records":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryRecord"}}}},"DictionaryRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"fullValue":{"type":"string","nullable":true},"deleted":{"type":"boolean"},"values":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/dictionaries/{dictionaryName}":{"post":{"summary":"Add value to Dictionary","tags":["Dictionaries"],"operationId":"Add_value_to_Dictionary","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"}],"responses":{"201":{"description":"Values added to dictionary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecordBatch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"### HTTP Request\n\n***POST*** `/{tenantName}/{instanceName}/dictionaries/{dictionaryName}`\n\nin our example it would be:\n\n***POST*** `https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 201 | Created |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecordBatch"}}}}}}}}
```

## Remove all values from Dictionary and set new

> Remove all values from dictionary and set new. Records will be deleted completely.\
> \
> \### HTTP Request\
> \
> \*\*\*PUT\*\*\* \`/{tenantName}/{instanceName}/dictionaries/{dictionaryName}\`\
> \
> in our example it would be:\
> \
> \*\*\*PUT\*\*\* \`<https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt\\`\\>
> \
> \*\*Responses\*\*\
> \
> \| Code | Description |\
> \| --- | --- |\
> \| 201 | Created |\
> \| 401 | Unauthorized |\
> \| 403 | Forbidden |\
> \| 404 | Not Found |

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Dictionaries","description":"APIs for working with dictionary infrastructure: records and formation There are 3 dictionaries by default: 1. Timezone(timezone) - cannot be changed or populated 2. CPT(cpt) and 3. ICD-10(icd-10) - cannot be changed, but can be populated."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"DictionaryName":{"name":"dictionaryName","in":"path","required":true,"description":"Machine-readable dictionary name","schema":{"type":"string"}}},"schemas":{"DictionaryRecordBatch":{"type":"object","properties":{"dictionaryName":{"type":"string","readOnly":true},"lastUpdatedAt":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"records":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryRecord"}}}},"DictionaryRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"fullValue":{"type":"string","nullable":true},"deleted":{"type":"boolean"},"values":{"type":"object","additionalProperties":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/dictionaries/{dictionaryName}":{"put":{"summary":"Remove all values from Dictionary and set new","tags":["Dictionaries"],"operationId":"Remove_all_values_from_Dictionary_and_set_new","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/DictionaryName"}],"responses":{"200":{"description":"Dictionary values replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecordBatch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Remove all values from dictionary and set new. Records will be deleted completely.\n\n### HTTP Request\n\n***PUT*** `/{tenantName}/{instanceName}/dictionaries/{dictionaryName}`\n\nin our example it would be:\n\n***PUT*** `https://api.live.welkincloud.io/gh/sb-demo/dictionaries/cpt`\n\n**Responses**\n\n| Code | Description |\n| --- | --- |\n| 201 | Created |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryRecordBatch"}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.welkinhealth.com/api-reference/dictionaries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.