Users

In most cases, a user is a person who is known to ClaimCenter and who is listed in the ClaimCenter 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 ClaimCenter but who are not listed in the ClaimCenter 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.

Note: Be aware that Cloud API enforces application constraints specified in internal code, but it does not enforce constraint specified in the user interface. This is because internal code constraints cannot be modified or removed, but user interface constraints can. As a result of this, there may be actions you can execute through Cloud API that you cannot execute through the base configuration user interface.

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}

To protect the sensitive information of any users associated with a claim, ClaimCenter only allows internal and external users with sufficient authorization to access the /admin/v1/users endpoint. For example, a claim's adjuster may be able to call the endpoint to view the users associated with the claim. However, the adjuster may not be able to use it to view users associated with another claim the adjuster isn't assigned to. This access is typically defined by the user's role. To learn more about this authorization strategy for internal users, see Overview of authentication for internal users. To learn about the strategy for external users, see Overview of authentication for external users.

External contacts with authorized contact authorization IDs, cc_contactAuthorizationIds, can call the /admin/v1/users endpoint. If the contact has a claim privileged role for the claim, such as 'Insured', the contact can see any users assigned to the claim. If the contact is a claimant for an exposure, the contact can see any users assigned to the exposure. To learn more about how the contact authorization ID strategy, see How the contactAuthorizationIds strategy manages access.

Producers can also call the /admin/v1/users endpoint. If the producer is a producer of service for a claim, like the insurance broker for its associated policy, the producer can see any users assigned to the claim, as well as any exposures where the claimant has a producer accessible role, such as 'Insured'. To learn more about how to manage producer access to resources, see How the producerCodes strategy manages access.

For example, the following is the snippet of the response payload when retrieving the information for user demo_sample:1 (Andy Applegate).

Command

GET /admin/v1/users/demo_sample:1

Response

{
    "data": {
        "attributes": {
            "active": true,
            "cellPhone": {
                "countryCode": {
                    "code": "US",
                    "name": "United States (1)"
                },
                "displayName": "650-333-3333",
                "number": "6503333333"
            },
            "displayName": "Andy Applegate",
            "emailAddress1": "aapplegate1@acmeins.com",
            "emailAddress2": "aapplegate1@personal.com",
            "employeeNumber": "1000001",
            "externalUser": false,
            "firstName": "Andy",
            "id": "demo_sample:1",
            "lastName": "Applegate",
            "roles": [
                {
                    "displayName": "Adjuster",
                    "id": "adjuster",
                    "type": "Role"
                },
                {
                    "displayName": "Trusted for Sensitive Claims",
                    "id": "sensitive_claims",
                    "type": "Role"
                }
            ],
            "username": "aapplegate",
            "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

Note: When a user is created through Cloud API, the user's password is set to a value that cannot be used for authentication. (The password is set to a value that is not a valid Base64 string, but the authentication framework can authenticate passwords only when they are valid Base64 strings.) In order for the new user to authenticate, the password must first be changed to a valid Base64 string through some other method, such as through the user interface.

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": "cc:SVA-tE4oV6qcNvofjff8v",
            "username": "amartin",
            "vacationStatus": {
                "code": "atwork",
                "name": "At work"
            }
        },
        "checksum": "590697d4d0c3ccc1728d9f2d1d8c4051",
        "links": {
            "self": {
                "href": "/admin/v1/users/cc:SVA-tE4oV6qcNvofjff8v",
                "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
Primary email address: adiaz@acmeins.com
Secondary email address: adiaz@personal.com
Employee number: ACME-02027
Roles: account manager (account_manager) and adjuster (adjuster)

POST /admin/v1/users

{
  "data": {
    "attributes": {
        "firstName": "Adriana",
        "lastName": "Diaz",
        "username": "adiaz",
        "emailAddress1": "adiaz@acmeins.com",
        "emailAddress2": "adiaz@personal.com",
        "employeeNumber": "ACME-02027",
        "roles" : [
            {
                "id": "account_manager"
            },
            {
                "id": "adjuster"
            }
        ]
    }
  }
}

When you create a user, you can also specify the user's roles and authority limit profile.

For more information on working with user roles, see User roles.
For more information on working with authority limit profiles, see Authority limit profiles.

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}

For example, the following request deletes user xc:2156:

DELETE /admin/v1/users/xc:2156

<no request body>