Users
In most cases, a user is a person who is known to PolicyCenter and who is listed in the PolicyCenter database (such as policy underwriters, claims adjusters, and billing clerks). Within the context of Cloud API authentication, this is also referred to as an internal user.
In some cases, a user can represent a service. This occurs for caller applications which are services which are mapped to user accounts for the purpose of managing access.
Do not confuse internal users with external users. External users are users known to PolicyCenter but who are not listed in the PolicyCenter database (such as account holders, policy holders, and service vendors).
For information on working with services and external users, see the Cloud API Developer Guide.
For example, there is no internal code that requires a user to have a phone number. Therefore, you can create and modify a user through Cloud API without ever specifying a primary phone number. However, the base configuration user interface does require you to specify a phone number. Therefore, any user that you modify through the base configuration user interface must have a phone number, even when that user was created through Cloud API without a phone number.
If there is a desire to have the constraints of the two environments match, insurers can add constraints to Cloud API and/or remove them from the user interface.
Querying for user information
To retrieve information about a user, you can use the following endpoints:
- GET
/admin/v1/users
- GET
/admin/v1/users/{userId}
For example, the following is the snippet of the response payload when retrieving the information for user pc:S-sAtIMQDbK0z3b2E7Mvw (Alice Applegate).
By default, only users in the requesting user’s organization will be returned. To retrieve users in all organizations, include the following filter query parameter:
GET /admin/v1/users?filter=*none
Command
GET /admin/v1/users/pc:S-sAtIMQDbK0z3b2E7Mvw
Response
{
"data": {
"attributes": {
"active": true,
"displayName": "Alice Applegate",
"externalUser": false,
"firstName": "Alice",
"groups": [
{
"displayName": "Los Angeles Branch UW",
"id": "pc:SSXQ8EaLxQq4LZ33Ia76r"
},
{
"displayName": "Eastern Region Underwriting",
"id": "pc:SVZTqTgdrHJKYQV9aGCbN"
}
],
"id": "pc:S-sAtIMQDbK0z3b2E7Mvw",
"lastName": "Applegate",
"organization": {
"displayName": "Enigma Fire & Casualty",
"id": "systemTables:1",
"type": "Organization",
"uri": "/admin/v1/organizations/systemTables:1"
},
"roles": [
{
"displayName": "Reinsurance Manager",
"id": "reinsurance_manager",
"type": "Role"
},
{
"displayName": "Underwriter",
"id": "underwriter",
"type": "Role"
}
],
"useOrgAddress": true,
"useProducerCodeSecurity": false,
"userType": {
"code": "underwriter",
"name": "Underwriter"
},
"username": "aapplegate",
"uwAuthorityProfiles": [
{
"displayName": "Underwriter 1",
"id": "pc:underwriter1",
"type": "UWAuthorityProfile",
"uri": "/admin/v1/uw-authority-profiles/pc:underwriter1"
}
],
"vacationStatus": {
"code": "atwork",
"name": "At work"
},
"workPhone": {
"displayName": "213-555-8164",
"number": "2135558164"
}
}
}
}
Creating users
To create a user, use the following endpoint:
- POST
/admin/v1/users
Create a minimal user
The minimum creation criteria for a user is the username
. For
example, the following request creates a user with the user name "amartin".
{
"data": {
"attributes": {
"username": "amartin"
}
}
}
The following is the response payload.
POST /admin/v1/users
{
"data": {
"attributes": {
"active": true,
"displayName": "",
"externalUser": false,
"id": "pc:SatEdbNuwVSfc2BvbG4g4",
"organization": {
"displayName": "Enigma Fire & Casualty",
"id": "systemTables:1",
"type": "Organization",
"uri": "/admin/v1/organizations/systemTables:1"
},
"useOrgAddress": true,
"useProducerCodeSecurity": false,
"userType": {
"code": "other",
"name": "Other"
},
"username": "amartin",
"vacationStatus": {
"code": "atwork",
"name": "At work"
}
},
"checksum": "8b01f84c8076ba3f8c235cb2483cdbfb",
"links": {
"self": {
"href": "/admin/v1/users/pc:SatEdbNuwVSfc2BvbG4g4",
"methods": [
"get",
"patch"
]
}
}
}
}
Create a typical user
You can specify additional information about a user as specified in the User schema. For example, the following payload creates a user with the following attributes:
- First name: Adriana
- Last name: Diaz
- User name: adiaz
- Employee number: ACME-02027
- Roles: audit examiner (
audit_examiner
) and audit supervisor (audit_supervisor
)
POST /admin/v1/users
{
"data": {
"attributes": {
"firstName": "Adriana",
"lastName": "Diaz",
"username": "adiaz",
"employeeNumber": "ACME-02027",
"roles" : [
{
"id": "audit_examiner"
},
{
"id": "audit_supervisor"
}
]
}
}
}
When you create a user, you can also specify the user's roles, authority profile, and producer codes (if the user is bound by producer code security).
- For more information on working with user roles, see User roles.
- For more information on working with authority profiles, see Authority profiles.
- For more information on working with a user's producer codes, see Producer codes.
Assigning a user to a group
You cannot assign a user to a group using the /admin/v1/users
endpoint. You must use the /admin/v1/groups/{groupId}/users
endpoint. For more information, see Assigning users to groups.
Updating users
Use the following endpoint to modify an existing user:
- PATCH
/admin/v1/users/{userId}
For example, the following request updates the first name of user xc:2156
PATCH /admin/v1/users/xc:2156
{
"data": {
"attributes": {
"firstName": "Alex"
}
}
}
Deleting users
Use the following endpoint to delete an existing user:
- DELETE
/admin/v1/users/{userId}
DELETE /admin/v1/users/xc:2156
<no request body>