Custom user attributes

You can use the Cloud API to apply custom user attributes to users to provide additional information about them. For example, you can apply a custom attribute of 'Spanish' to indicate a user's level of Spanish fluency. You cannot apply custom user attributes from the BillingCenter UI itself, so to learn more about custom user attributes, refer to refer to in ClaimCenter.

You can further customize the user's specific attribute by defining the following optional user-specific attributes:
  • State: Defines the state (in the United States) or jurisdiction where the attribute is valid. An expert in workers’ compensation policies usually has expertise in just one state or jurisdiction.
  • Value: Defines an integer value for an attribute. Language fluency might be rated on a 1-5 scale.

This topic provides a high-level overview of custom user attributes, discussing both what they are and how to work with them through the Cloud API. Read this topic to learn how to use the API to apply custom attributes to users and manage those attribute. To learn more about how to create and manage the custom attributes themselves with the API, refer to Attributes.

Querying for custom user attributes

Use the following endpoints to query for a user's custom attributes:

  • GET /admin/v1/users/{userId}/attributes
  • GET /admin/v1/user/{userId}/attributes/{userAttributeId}

The first endpoint retrieves a collection of a user's custom attributes and their details. For example, the following request retrieves a user's custom attributes.

Command

GET /admin/v1/users/xc:SEwVjUe1h60Uv5tI5XdMn/attributes

Response


{
    "count": 2,
    "data": [
        {
            "attributes": {
                "attribute": {
                    "displayName": "Auto-Expertise",
                    "id": "xc:S-uIjtMevbbhKwYINaQhW",
                    "type": "Attribute",
                    "uri": "/admin/v1/attributes/xc:S-uIjtMevbbhKwYINaQhW"
                },
                "id": "xc:S3kZkWAJeZoDd5ZWP7Ybf",
                "state": {
                    "code": "CA",
                    "name": "California"
                },
                "value": 4
            }
        },
        {
            "attributes": {
                "attribute": {
                    "displayName": "French"
                    "id": "xc:Sk15XVYWTjBDfXB9wrfOV",
                    "type": "Attribute",
                    "uri": "/admin/v1/attributes/xc:Sk15XVYWTjBDfXB9wrfOV"
                },
                "id": "xc:SWk7ULSUWIgKRPHzd2BFz",
                "state": {
                    "code": "CA",
                    "name": "California"
                },
                "value": 5
            } 
        }
    ]
}

You can use the id in the response to retrieve that specific custom attribute belonging to the user. For example, the following request retrieves only the user's attribute xc:SWk7ULSUWIgKRPHzd2BFz.

Note: The id within the attributes object is the id of the custom attribute itself, not the attribute applied to the user. To learn more about the attributes themselves and how to manage them, refer to Attributes.

Command

GET /admin/v1/users/xc:SEwVjUe1h60Uv5tI5XdMn/attributes/xc:SWk7ULSUWIgKRPHzd2BFz

Response


{
    "data": {
        "attributes": {
            "displayName": "French",
            "id": "xc:Sk15XVYWTjBDfXB9wrfOV",
            "type": "Attribute",
            "uri": "/admin/v1/attributes/xc:Sk15XVYWTjBDfXB9wrfOV"
        },
        "id": "xc:SWk7ULSUWIgKRPHzd2BFz",
        "state": {
            "code": "CA",
            "name": "California"
        },
        "value": 5
    }
}

Creating custom user attributes

Use the following request to create a custom user attribute:

  • POST /admin/v1/users/{userId}/attributes

The request applies an existing custom attribute to a user.

Create a minimal custom user attribute

The only required field is the id (within the attribute object) of the custom attribute to apply to the user. For example, the following request applies the attribute xc:S-uIjtMevbbhKwYINaQhW to a user.

Note: To learn how to see every custom user attribute id you can apply, refer to Querying for attributes.

Command

POST /admin/v1/users/xc:SEwVjUe1h60Uv5tI5XdMn/attributes
Request

{
    "data": {
        "attributes": {
            "attribute": {
                "id": "xc:S-uIjtMevbbhKwYINaQhW"
            }
        }
    }
}

The API responds with the created user attribute.

Response


{
    "data": {
        "attributes": {
            "attribute": {
                "displayName": "Worker's Compensation",
                "id": "xc:S-uIjtMevbbhKwYINaQhW",
                "type": "Attribute",
                "uri": "/admin/v1/attributes/xc:S-uIjtMevbbhKwYINaQhW"
            },
            "id": "xc:S3kZkWAJeZoDd5ZWP7Ybf"
        }
    }
}

The response includes a second id, xc:S3kZkWAJeZoDd5ZWP7Ybf. This id refers to the specific attribute applied to the user, not the attribute itself. You can use this id to retrieve and modify the user attribute.

Create a typical custom user attribute

When you apply a custom attribute to a user, you can further customize the attribute for the user by specifying values for the following fields:
  • state/code
  • value

If you're creating a custom attribute for a user, you would typically specify values for one or both of these fields. The state defines the state or jurisdiction where the attribute is valid, such as an expert in workers' compensation claims having expertise in only one state or jurisdiction. The value defines an integer value for an attribute, such as language fluency being rated on a 1-5 scale. For example, the following request applies the xc:S-uIjtMevbbhKwYINaQhW attribute to a user, along with the additional information.

Note: The code within state is a String that represents a TypeKey defined in the State typelist of available codes, so you can only use a value enumerated in that list. To learn how to access this typelist and see which codes are available, refer to Typelist metadata.

Request


{
    "data": {
        "attributes": {
            "attribute": {
                "id": "xc:S-uIjtMevbbhKwYINaQhW"
            },
            "state": {
                "code": "MN"
            },
            "value": 5
        }
    }
}

Response


{
    "data": {
        "attributes": {
            "attribute": {
                "displayName": "Worker's Compensation",
                "id": "xc:SPhpXiegc0R8SqTsSrL4y",
                "type": "Attribute",
                "uri": "/admin/v1/attributes/xc:S-uIjtMevbbhKwYINaQhW"
            },
            "id": "xc:SmbozcHL5CXDhMyv9b4k1",
            "state": {
                "code": "MN",
                "name": "Minnesota"
            },
            "value": 5
        }
    }
}

Modifying custom user attributes

Use the following endpoint to modify an existing custom user attribute:

  • PATCH /admin/v1/users/{userId}/attributes/{userAttributeId}

You can modify the following fields:

  • state/code
  • value
For example, the following request modifies the code within state for the custom user attribute xc:SQLnVozT4-lE4siO9c6YO.
Note: The code within state is a String that represents a TypeKey defined in the State typelist of available codes, so you can only use a value enumerated in that list. To learn how to access this typelist and see which codes are available, refer to Typelist metadata.

Command

PATCH /admin/v1/users/xc:SEwVjUe1h60Uv5tI5XdMn/attributes/xc:SQLnVozT4-lE4siO9c6YO

Request


{
    "data": {
        "attributes": {
            "state": {
                "code": "OH"
            }
        }
    }
}

The API responds with the updated user attribute.

Response


{
    "data": {
        "attributes": {
            "attribute": {
                "displayName": "French",
                "id": "xc:Sk15XVYWTjBDfXB9wrfOV",
                "type": "Attribute", 
                "uri": "/admin/v1/attributes/xc:SQLnVozT4-lE4siO9c6YO"
            },
            "id": "xc:SQLnVozT4-lE4siO9c6YO",
            "state": {
                "code": "OH",
                "name": "Ohio"
            },
            "value": 5
        }
    }
}

Deleting custom user attributes

Use the following endpoint to delete a user's custom attribute:

  • DELETE /admin/v1/users/{userId}/attributes/{userAttributeId}

For example, the following request deletes the custom attribute xc:S80CwAUpLu62Gx9ZwPpZ0 from the user xc:SEwVjUe1h60Uv5tI5XdMn.

Command

DELETE /admin/v1/users/xc:SEwVjUe1h60Uv5tI5XdMn/attributes/xc:Sk15XVYWTjBDfXB9wrfOV

When the API has successfully deleted the user attribute, it will return an empty body in response.