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

# User

This API allows one to work with User records

## Create/Update User Territories

> \_Note: Available only if Admin Access -> User Regions is set.\_\
> \
> \### Example overview\
> \
> From \`live\` instance assigned region \`washington\` with territories \`seattle\` and \`tacoma\` and from \`stage\` instance assigned region \`california\` with territory \`los-angeles\` for user \`20eb246e-8099-4c7c-854c-5e0f9a366ddb\`.\
> \
> \### HTTP Request\
> \
> \*\*Method\*\*: \_\*\*PUT\*\*\_\
> \
> \*\*Endpoint\*\*: \`{{url}}/{{tenantName}}/admin/user-territories/{{userId}}\`\
> \
> in our example it would be: \`<https://api.live.welkincloud.io/gh/admin/user-territories/20eb246e-8099-4c7c-854c-5e0f9a366ddb\\`\\>
> \
> \*\*Parameters\*\*\
> \
> \| Name | Located in | Description | Required | Type |\
> \| --- | --- | --- | --- | --- |\
> \| tenantName | path | Name of tenant | Yes | string |\
> \| userId | path | User identifier | Yes | UUID |\
> \| territories.name | body | Region name | Yes | string |\
> \| territories.territories | body | Territory names | Yes | \\\[string\\] |\
> \| territories.instanceName | body | Instance name | Yes | string |\
> \
> \*\*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":"User","description":"This API allows one to work with User records"}],"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"}},"UserId":{"name":"userId","in":"path","required":true,"description":"UUID of the user","schema":{"type":"string","format":"uuid"}}},"schemas":{"UserTerritory":{"type":"object","required":["userId","territories"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"userId":{"type":"string","format":"uuid"},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"fullTerritoriesAccessInstances":{"type":"array","items":{"type":"string"}}}},"ClientTerritory":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}},"instanceName":{"type":"string","nullable":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}/admin/user-territories/{userId}":{"put":{"summary":"Create/Update User Territories","tags":["User"],"operationId":"Create_Update_User_Territories","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/UserId"}],"responses":{"200":{"description":"User territories created/updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserTerritory"}}}},"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":"_Note: Available only if Admin Access -> User Regions is set._\n\n### Example overview\n\nFrom `live` instance assigned region `washington` with territories `seattle` and `tacoma` and from `stage` instance assigned region `california` with territory `los-angeles` for user `20eb246e-8099-4c7c-854c-5e0f9a366ddb`.\n\n### HTTP Request\n\n**Method**: _**PUT**_\n\n**Endpoint**: `{{url}}/{{tenantName}}/admin/user-territories/{{userId}}`\n\nin our example it would be: `https://api.live.welkincloud.io/gh/admin/user-territories/20eb246e-8099-4c7c-854c-5e0f9a366ddb`\n\n**Parameters**\n\n| Name | Located in | Description | Required | Type |\n| --- | --- | --- | --- | --- |\n| tenantName | path | Name of tenant | Yes | string |\n| userId | path | User identifier | Yes | UUID |\n| territories.name | body | Region name | Yes | string |\n| territories.territories | body | Territory names | Yes | \\[string\\] |\n| territories.instanceName | body | Instance name | Yes | string |\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/UserTerritory"}}}}}}}}
```

## Read Users Records

> User Record API url consist of the following structure\
> \
> \`<https://api.live.welkincloud.io/{}/admin/users\\`\\>
> \
> In our example, the url would be: \`<https://api.live.welkincloud.io/gh/admin/users\\`\\>
> \
> 1\. HTTP Method: GET\
> &#x20;   \
> 2\. HTTP URL: \`<https://api.live.welkincloud.io/gh/admin/users\\`>

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"User","description":"This API allows one to work with User records"}],"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"}},"Size":{"name":"size","in":"query","required":false,"description":"Number of results per page","schema":{"type":"integer","default":20,"minimum":1,"maximum":1000}},"Sort":{"name":"sort","in":"query","required":false,"description":"Sort field and direction, e.g. `lastName,asc` or `createdAt,desc`","schema":{"type":"string"}}},"schemas":{"UserPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"metaInfo":{"$ref":"#/components/schemas/PageMetaInfo"}}},"User":{"type":"object","required":["username","email","locale"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"username":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format","nullable":true},"timezone":{"type":"string","nullable":true},"locale":{"$ref":"#/components/schemas/UserLocale","default":"en-US"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"credentials":{"type":"string","nullable":true},"tenantName":{"type":"string","readOnly":true},"enabled":{"type":"boolean","default":true},"mfaEnabled":{"type":"boolean","default":false},"statusType":{"type":"string","nullable":true,"description":"AWS Cognito user status."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"_root_user":{"type":"boolean","readOnly":true},"ssoAccess":{"type":"boolean"},"passwordAccess":{"type":"boolean","default":true},"terminologyName":{"type":"string","nullable":true},"userState":{"$ref":"#/components/schemas/UserState"},"customUserAttributes":{"type":"object","additionalProperties":true},"allowedToReceiveCalls":{"type":"boolean","default":true},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"fullTerritoriesAccessInstances":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"seats":{"type":"array","items":{"$ref":"#/components/schemas/LicenseSeatType"}},"seatAssignAllowed":{"type":"boolean"},"applicationAccess":{"$ref":"#/components/schemas/UserAppAccess"},"createdByName":{"type":"string","readOnly":true},"updatedByName":{"type":"string","readOnly":true}}},"UserLocale":{"type":"string","enum":["en-US","en-SG","en-AU","en-AE","en-EU"]},"UserState":{"type":"string","enum":["PROVISIONED","ACTIVE","INACTIVE"]},"ClientTerritory":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}},"instanceName":{"type":"string","nullable":true}}},"Permission":{"type":"object","required":["permissionName","instanceName","type"],"properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"permissionName":{"type":"string"},"instanceName":{"type":"string"},"type":{"$ref":"#/components/schemas/PermissionType"},"effectiveDate":{"type":"string","format":"date-time","nullable":true},"expirationDate":{"type":"string","format":"date-time","nullable":true},"primaryRole":{"type":"boolean","nullable":true,"description":"Only meaningful when type is SECURITY_ROLE."}}},"PermissionType":{"type":"string","enum":["SECURITY_POLICY","SECURITY_ROLE"]},"LicenseSeatType":{"type":"string","enum":["GENERAL"]},"UserAppAccess":{"type":"object","required":["userId","instanceAccesses"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"userId":{"type":"string","format":"uuid"},"adminAccessEnabled":{"type":"boolean"},"auditSecurityAccessEnabled":{"type":"boolean"},"instanceAccesses":{"type":"array","items":{"$ref":"#/components/schemas/InstanceAccess"}}}},"InstanceAccess":{"type":"object","required":["instanceId"],"properties":{"instanceId":{"type":"string","format":"uuid"},"instanceName":{"type":"string","nullable":true},"instanceDescription":{"type":"string","nullable":true},"userEmailWithInstanceDomain":{"type":"string","nullable":true},"workshopAccessEnabled":{"type":"boolean"},"auditDataAccessEnabled":{"type":"boolean"},"enabledTakenPersonally":{"type":"boolean"}}},"PageMetaInfo":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalElements":{"type":"integer"},"numberOfElements":{"type":"integer"}}}},"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}/admin/users":{"get":{"summary":"Read Users Records","tags":["User"],"operationId":"Read_Users_Records","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/Size"},{"$ref":"#/components/parameters/Sort"},{"name":"email","in":"query","required":false,"schema":{"type":"string"}},{"name":"ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"uuid,uuid,uuid......"},{"name":"firstName","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"lastName","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"territories","in":"query","required":false,"schema":{"type":"string"},"description":"string,string,string....\nWorks only with seted region filter"},{"name":"roleName","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"includeDeleted","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination: page number"}],"responses":{"200":{"description":"Paginated list of users. Note: the backend has no `includeDeleted` filter — this query param may not have an effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPage"}}}},"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":"User Record API url consist of the following structure\n\n`https://api.live.welkincloud.io/{}/admin/users`\n\nIn our example, the url would be: `https://api.live.welkincloud.io/gh/admin/users`\n\n1. HTTP Method: GET\n    \n2. HTTP URL: `https://api.live.welkincloud.io/gh/admin/users`"}}}}
```

## Create User Record

> \_NOTE: Available only if Admin Access ->\_ User Provision  \
> \_is set.\_\
> \
> Users API url consist of the following structure\
> \
> \`<https://api.live.welkincloud.io/{}/admin/users\\`\\>
> \
> In our example, the url would be: \`<https://api.live.welkincloud.io/gh/admin/users\\`\\>
> \
> 1\. HTTP Method: POST\
> 2\. HTTP URL: \`<https://api.live.welkincloud.io/gh/admin/users\\`\\>
> &#x20;   \
> \
> \*\*Note:\*\*\
> \
> \- \*\*phone:\*\* when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"User","description":"This API allows one to work with User records"}],"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"}}},"schemas":{"User":{"type":"object","required":["username","email","locale"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"username":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format","nullable":true},"timezone":{"type":"string","nullable":true},"locale":{"$ref":"#/components/schemas/UserLocale","default":"en-US"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"credentials":{"type":"string","nullable":true},"tenantName":{"type":"string","readOnly":true},"enabled":{"type":"boolean","default":true},"mfaEnabled":{"type":"boolean","default":false},"statusType":{"type":"string","nullable":true,"description":"AWS Cognito user status."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"_root_user":{"type":"boolean","readOnly":true},"ssoAccess":{"type":"boolean"},"passwordAccess":{"type":"boolean","default":true},"terminologyName":{"type":"string","nullable":true},"userState":{"$ref":"#/components/schemas/UserState"},"customUserAttributes":{"type":"object","additionalProperties":true},"allowedToReceiveCalls":{"type":"boolean","default":true},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"fullTerritoriesAccessInstances":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"seats":{"type":"array","items":{"$ref":"#/components/schemas/LicenseSeatType"}},"seatAssignAllowed":{"type":"boolean"},"applicationAccess":{"$ref":"#/components/schemas/UserAppAccess"},"createdByName":{"type":"string","readOnly":true},"updatedByName":{"type":"string","readOnly":true}}},"UserLocale":{"type":"string","enum":["en-US","en-SG","en-AU","en-AE","en-EU"]},"UserState":{"type":"string","enum":["PROVISIONED","ACTIVE","INACTIVE"]},"ClientTerritory":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}},"instanceName":{"type":"string","nullable":true}}},"Permission":{"type":"object","required":["permissionName","instanceName","type"],"properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"permissionName":{"type":"string"},"instanceName":{"type":"string"},"type":{"$ref":"#/components/schemas/PermissionType"},"effectiveDate":{"type":"string","format":"date-time","nullable":true},"expirationDate":{"type":"string","format":"date-time","nullable":true},"primaryRole":{"type":"boolean","nullable":true,"description":"Only meaningful when type is SECURITY_ROLE."}}},"PermissionType":{"type":"string","enum":["SECURITY_POLICY","SECURITY_ROLE"]},"LicenseSeatType":{"type":"string","enum":["GENERAL"]},"UserAppAccess":{"type":"object","required":["userId","instanceAccesses"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"userId":{"type":"string","format":"uuid"},"adminAccessEnabled":{"type":"boolean"},"auditSecurityAccessEnabled":{"type":"boolean"},"instanceAccesses":{"type":"array","items":{"$ref":"#/components/schemas/InstanceAccess"}}}},"InstanceAccess":{"type":"object","required":["instanceId"],"properties":{"instanceId":{"type":"string","format":"uuid"},"instanceName":{"type":"string","nullable":true},"instanceDescription":{"type":"string","nullable":true},"userEmailWithInstanceDomain":{"type":"string","nullable":true},"workshopAccessEnabled":{"type":"boolean"},"auditDataAccessEnabled":{"type":"boolean"},"enabledTakenPersonally":{"type":"boolean"}}}},"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}/admin/users":{"post":{"summary":"Create User Record","tags":["User"],"operationId":"Create_User_Record","parameters":[{"$ref":"#/components/parameters/TenantName"}],"responses":{"201":{"description":"User created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"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":"_NOTE: Available only if Admin Access ->_ User Provision  \n_is set._\n\nUsers API url consist of the following structure\n\n`https://api.live.welkincloud.io/{}/admin/users`\n\nIn our example, the url would be: `https://api.live.welkincloud.io/gh/admin/users`\n\n1. HTTP Method: POST\n2. HTTP URL: `https://api.live.welkincloud.io/gh/admin/users`\n    \n\n**Note:**\n\n- **phone:** when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}}}}
```

## Read User Record

> User Record API url consist of the following structure:\
> \
> 1\. Get user by UserName\
> &#x20;   \
> \
> {{url}}/{{tenantName}}//admin/users/{userName}\
> \
> 2\\. Get User By ID  \
> {{url}}/{{tenantName}}/admin/users/{userId}?type=ID\
> \
> 3\\. Get User by Email  \
> {{url}}/{{tenantName}}/admin/users/{userEmail}?type=EMAIL\
> \
> In our example, the url would be: \`<https://api.live.welkincloud.io/gh/admin/users/johndoe\\`\\>
> \
> 1\. HTTP Method: GET\
> &#x20;   \
> 2\. HTTP URL: \`<https://api.live.welkincloud.io/gh/admin/users/johndoe\\`>

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"User","description":"This API allows one to work with User records"}],"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"}},"UserName":{"name":"userName","in":"path","required":true,"description":"Username of the user","schema":{"type":"string"}}},"schemas":{"User":{"type":"object","required":["username","email","locale"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"username":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format","nullable":true},"timezone":{"type":"string","nullable":true},"locale":{"$ref":"#/components/schemas/UserLocale","default":"en-US"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"credentials":{"type":"string","nullable":true},"tenantName":{"type":"string","readOnly":true},"enabled":{"type":"boolean","default":true},"mfaEnabled":{"type":"boolean","default":false},"statusType":{"type":"string","nullable":true,"description":"AWS Cognito user status."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"_root_user":{"type":"boolean","readOnly":true},"ssoAccess":{"type":"boolean"},"passwordAccess":{"type":"boolean","default":true},"terminologyName":{"type":"string","nullable":true},"userState":{"$ref":"#/components/schemas/UserState"},"customUserAttributes":{"type":"object","additionalProperties":true},"allowedToReceiveCalls":{"type":"boolean","default":true},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"fullTerritoriesAccessInstances":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"seats":{"type":"array","items":{"$ref":"#/components/schemas/LicenseSeatType"}},"seatAssignAllowed":{"type":"boolean"},"applicationAccess":{"$ref":"#/components/schemas/UserAppAccess"},"createdByName":{"type":"string","readOnly":true},"updatedByName":{"type":"string","readOnly":true}}},"UserLocale":{"type":"string","enum":["en-US","en-SG","en-AU","en-AE","en-EU"]},"UserState":{"type":"string","enum":["PROVISIONED","ACTIVE","INACTIVE"]},"ClientTerritory":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}},"instanceName":{"type":"string","nullable":true}}},"Permission":{"type":"object","required":["permissionName","instanceName","type"],"properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"permissionName":{"type":"string"},"instanceName":{"type":"string"},"type":{"$ref":"#/components/schemas/PermissionType"},"effectiveDate":{"type":"string","format":"date-time","nullable":true},"expirationDate":{"type":"string","format":"date-time","nullable":true},"primaryRole":{"type":"boolean","nullable":true,"description":"Only meaningful when type is SECURITY_ROLE."}}},"PermissionType":{"type":"string","enum":["SECURITY_POLICY","SECURITY_ROLE"]},"LicenseSeatType":{"type":"string","enum":["GENERAL"]},"UserAppAccess":{"type":"object","required":["userId","instanceAccesses"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"userId":{"type":"string","format":"uuid"},"adminAccessEnabled":{"type":"boolean"},"auditSecurityAccessEnabled":{"type":"boolean"},"instanceAccesses":{"type":"array","items":{"$ref":"#/components/schemas/InstanceAccess"}}}},"InstanceAccess":{"type":"object","required":["instanceId"],"properties":{"instanceId":{"type":"string","format":"uuid"},"instanceName":{"type":"string","nullable":true},"instanceDescription":{"type":"string","nullable":true},"userEmailWithInstanceDomain":{"type":"string","nullable":true},"workshopAccessEnabled":{"type":"boolean"},"auditDataAccessEnabled":{"type":"boolean"},"enabledTakenPersonally":{"type":"boolean"}}}},"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}/admin/users/{userName}":{"get":{"summary":"Read User Record","tags":["User"],"operationId":"Read_User_Record","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/UserName"},{"name":"email","in":"query","required":false,"schema":{"type":"string"}},{"name":"ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"uuid,uuid,uuid......"},{"name":"firstName","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"lastName","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"string"},{"name":"territories","in":"query","required":false,"schema":{"type":"string"},"description":"string,string,string....\nWorks only with seted region filter"},{"name":"includeDeleted","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination: page number"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"Pagination: page size"},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort field with sorting order(asc or desc) after coma"}],"responses":{"200":{"description":"User record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"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":"User Record API url consist of the following structure:\n\n1. Get user by UserName\n    \n\n{{url}}/{{tenantName}}//admin/users/{userName}\n\n2\\. Get User By ID  \n{{url}}/{{tenantName}}/admin/users/{userId}?type=ID\n\n3\\. Get User by Email  \n{{url}}/{{tenantName}}/admin/users/{userEmail}?type=EMAIL\n\nIn our example, the url would be: `https://api.live.welkincloud.io/gh/admin/users/johndoe`\n\n1. HTTP Method: GET\n    \n2. HTTP URL: `https://api.live.welkincloud.io/gh/admin/users/johndoe`"}}}}
```

## Update User Record (Partial update)

> 1\. \*\*User is in Provision state\*\* (users that were created by API clients and have not been activated by administrators yet)\
> &#x20;   \
> \
> \_NOTE: Available only if Admin Access ->\_ User Provision  \
> \_is set.\_\
> \
> All fields can be changed.\
> \
> \*\*2\\. User is not in Provision state\*\*\
> \
> \_NOTE: Available only if Admin Access ->\_ User Attributes  \
> \_is set.\_\
> \
> Fields that can be changed:\
> \
> \- credentials\
> &#x20;   \
> \- timezone\
> &#x20;   \
> \- locale\
> &#x20;   \
> \- custom attributes\
> &#x20;   \
> \
> If you with to update some of the user fields, but not all, you can use \`PATCH\`\
> \
> 1\. HTTP Method: PATCH\
> &#x20;   \
> 2\. HTTP URL: \`<https://api.live.welkincloud.io/gh/admin/users/johndoe\\`>

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"User","description":"This API allows one to work with User records"}],"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"}},"UserName":{"name":"userName","in":"path","required":true,"description":"Username of the user","schema":{"type":"string"}}},"schemas":{"User":{"type":"object","required":["username","email","locale"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"username":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format","nullable":true},"timezone":{"type":"string","nullable":true},"locale":{"$ref":"#/components/schemas/UserLocale","default":"en-US"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"credentials":{"type":"string","nullable":true},"tenantName":{"type":"string","readOnly":true},"enabled":{"type":"boolean","default":true},"mfaEnabled":{"type":"boolean","default":false},"statusType":{"type":"string","nullable":true,"description":"AWS Cognito user status."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"_root_user":{"type":"boolean","readOnly":true},"ssoAccess":{"type":"boolean"},"passwordAccess":{"type":"boolean","default":true},"terminologyName":{"type":"string","nullable":true},"userState":{"$ref":"#/components/schemas/UserState"},"customUserAttributes":{"type":"object","additionalProperties":true},"allowedToReceiveCalls":{"type":"boolean","default":true},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"fullTerritoriesAccessInstances":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"seats":{"type":"array","items":{"$ref":"#/components/schemas/LicenseSeatType"}},"seatAssignAllowed":{"type":"boolean"},"applicationAccess":{"$ref":"#/components/schemas/UserAppAccess"},"createdByName":{"type":"string","readOnly":true},"updatedByName":{"type":"string","readOnly":true}}},"UserLocale":{"type":"string","enum":["en-US","en-SG","en-AU","en-AE","en-EU"]},"UserState":{"type":"string","enum":["PROVISIONED","ACTIVE","INACTIVE"]},"ClientTerritory":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}},"instanceName":{"type":"string","nullable":true}}},"Permission":{"type":"object","required":["permissionName","instanceName","type"],"properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"permissionName":{"type":"string"},"instanceName":{"type":"string"},"type":{"$ref":"#/components/schemas/PermissionType"},"effectiveDate":{"type":"string","format":"date-time","nullable":true},"expirationDate":{"type":"string","format":"date-time","nullable":true},"primaryRole":{"type":"boolean","nullable":true,"description":"Only meaningful when type is SECURITY_ROLE."}}},"PermissionType":{"type":"string","enum":["SECURITY_POLICY","SECURITY_ROLE"]},"LicenseSeatType":{"type":"string","enum":["GENERAL"]},"UserAppAccess":{"type":"object","required":["userId","instanceAccesses"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"userId":{"type":"string","format":"uuid"},"adminAccessEnabled":{"type":"boolean"},"auditSecurityAccessEnabled":{"type":"boolean"},"instanceAccesses":{"type":"array","items":{"$ref":"#/components/schemas/InstanceAccess"}}}},"InstanceAccess":{"type":"object","required":["instanceId"],"properties":{"instanceId":{"type":"string","format":"uuid"},"instanceName":{"type":"string","nullable":true},"instanceDescription":{"type":"string","nullable":true},"userEmailWithInstanceDomain":{"type":"string","nullable":true},"workshopAccessEnabled":{"type":"boolean"},"auditDataAccessEnabled":{"type":"boolean"},"enabledTakenPersonally":{"type":"boolean"}}},"UserUpdateRequest":{"type":"object","description":"Partial update — all fields optional.","properties":{"phone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"credentials":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"locale":{"$ref":"#/components/schemas/UserLocale"},"enabled":{"type":"boolean"},"mfaEnabled":{"type":"boolean"},"terminologyName":{"type":"string"},"ssoAccess":{"type":"boolean"},"passwordAccess":{"type":"boolean"},"resetPassword":{"type":"boolean"},"customUserAttributes":{"type":"object","additionalProperties":true,"nullable":true},"seats":{"type":"array","items":{"$ref":"#/components/schemas/LicenseSeatType"}},"allowedToReceiveCalls":{"type":"boolean"}}}},"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}/admin/users/{userName}":{"patch":{"summary":"Update User Record (Partial update)","tags":["User"],"operationId":"Update_User_Record_Partial_update","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/UserName"}],"responses":{"200":{"description":"Updated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"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":"1. **User is in Provision state** (users that were created by API clients and have not been activated by administrators yet)\n    \n\n_NOTE: Available only if Admin Access ->_ User Provision  \n_is set._\n\nAll fields can be changed.\n\n**2\\. User is not in Provision state**\n\n_NOTE: Available only if Admin Access ->_ User Attributes  \n_is set._\n\nFields that can be changed:\n\n- credentials\n    \n- timezone\n    \n- locale\n    \n- custom attributes\n    \n\nIf you with to update some of the user fields, but not all, you can use `PATCH`\n\n1. HTTP Method: PATCH\n    \n2. HTTP URL: `https://api.live.welkincloud.io/gh/admin/users/johndoe`","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserUpdateRequest"}}}}}}}}
```

## Update policies

> Request to set policies and roles for a user\
> \
> \_NOTE: Available only if Admin Access ->\_ User Provision \_is set for API client.\_

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"User","description":"This API allows one to work with User records"}],"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"}},"UserName":{"name":"userName","in":"path","required":true,"description":"Username of the user","schema":{"type":"string"}}},"schemas":{"User":{"type":"object","required":["username","email","locale"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"username":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format","nullable":true},"timezone":{"type":"string","nullable":true},"locale":{"$ref":"#/components/schemas/UserLocale","default":"en-US"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"credentials":{"type":"string","nullable":true},"tenantName":{"type":"string","readOnly":true},"enabled":{"type":"boolean","default":true},"mfaEnabled":{"type":"boolean","default":false},"statusType":{"type":"string","nullable":true,"description":"AWS Cognito user status."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"_root_user":{"type":"boolean","readOnly":true},"ssoAccess":{"type":"boolean"},"passwordAccess":{"type":"boolean","default":true},"terminologyName":{"type":"string","nullable":true},"userState":{"$ref":"#/components/schemas/UserState"},"customUserAttributes":{"type":"object","additionalProperties":true},"allowedToReceiveCalls":{"type":"boolean","default":true},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"fullTerritoriesAccessInstances":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"seats":{"type":"array","items":{"$ref":"#/components/schemas/LicenseSeatType"}},"seatAssignAllowed":{"type":"boolean"},"applicationAccess":{"$ref":"#/components/schemas/UserAppAccess"},"createdByName":{"type":"string","readOnly":true},"updatedByName":{"type":"string","readOnly":true}}},"UserLocale":{"type":"string","enum":["en-US","en-SG","en-AU","en-AE","en-EU"]},"UserState":{"type":"string","enum":["PROVISIONED","ACTIVE","INACTIVE"]},"ClientTerritory":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"territories":{"type":"array","items":{"type":"string"}},"instanceName":{"type":"string","nullable":true}}},"Permission":{"type":"object","required":["permissionName","instanceName","type"],"properties":{"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"permissionName":{"type":"string"},"instanceName":{"type":"string"},"type":{"$ref":"#/components/schemas/PermissionType"},"effectiveDate":{"type":"string","format":"date-time","nullable":true},"expirationDate":{"type":"string","format":"date-time","nullable":true},"primaryRole":{"type":"boolean","nullable":true,"description":"Only meaningful when type is SECURITY_ROLE."}}},"PermissionType":{"type":"string","enum":["SECURITY_POLICY","SECURITY_ROLE"]},"LicenseSeatType":{"type":"string","enum":["GENERAL"]},"UserAppAccess":{"type":"object","required":["userId","instanceAccesses"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"userId":{"type":"string","format":"uuid"},"adminAccessEnabled":{"type":"boolean"},"auditSecurityAccessEnabled":{"type":"boolean"},"instanceAccesses":{"type":"array","items":{"$ref":"#/components/schemas/InstanceAccess"}}}},"InstanceAccess":{"type":"object","required":["instanceId"],"properties":{"instanceId":{"type":"string","format":"uuid"},"instanceName":{"type":"string","nullable":true},"instanceDescription":{"type":"string","nullable":true},"userEmailWithInstanceDomain":{"type":"string","nullable":true},"workshopAccessEnabled":{"type":"boolean"},"auditDataAccessEnabled":{"type":"boolean"},"enabledTakenPersonally":{"type":"boolean"}}},"UserPoliciesUpdateRequest":{"type":"object","required":["instanceName"],"properties":{"instanceName":{"type":"string"},"fullTerritoriesAccess":{"type":"boolean"},"territories":{"type":"array","items":{"$ref":"#/components/schemas/ClientTerritory"}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}}}}},"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}/admin/users/{userName}/policies":{"put":{"summary":"Update policies","tags":["User"],"operationId":"Update_policies","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/UserName"}],"responses":{"200":{"description":"Updated user with new policies/roles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"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":"Request to set policies and roles for a user\n\n_NOTE: Available only if Admin Access ->_ User Provision _is set for API client._","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPoliciesUpdateRequest"}}}}}}}}
```


---

# 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/user.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.