UserAttribute : Manage User Attributes
Get All User Attributes
GET/api/3.0/user_attributes
all_user_attributes(fields, sorts)
Implementation Notes
Get information about all user attributes.
Response Class
array
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| fields | false | Requested fields. | string | string |
| sorts | false | Fields to sort by. | string | string |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
Create User Attribute
POST/api/3.0/user_attributes
create_user_attribute(body, fields)
Implementation Notes
Create a new user attribute.
Response Class
UserAttribute {
id (long, read-only): Unique Id,
name (string): Name of user attribute,
label (string): Human-friendly label for user attribute,
type (string): Type of user attribute ("string", "number", "datetime", "yesno", "zipcode"),
default_value (string): Default value for when no value is set on the user,
is_system (boolean, read-only): Attribute is a system default,
value_is_hidden (boolean): If true, users will not be able to view values of this attribute,
user_can_view (boolean): Non-admin users can see the values of their attributes and use them in filters,
user_can_edit (boolean): Users can change the value of this attribute for themselves,
hidden_value_domain_whitelist (string): Destinations to which a hidden attribute may be sent. Once set, cannot be edited.,
can (object, read-only): Operations the current user is able to perform on this object
}
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| body | false | User Attribute | body |
UserAttribute {
id (long, read-only): Unique Id, name (string): Name of user attribute, label (string): Human-friendly label for user attribute, type (string): Type of user attribute ("string", "number", "datetime", "yesno", "zipcode"), default_value (string): Default value for when no value is set on the user, is_system (boolean, read-only): Attribute is a system default, value_is_hidden (boolean): If true, users will not be able to view values of this attribute, user_can_view (boolean): Non-admin users can see the values of their attributes and use them in filters, user_can_edit (boolean): Users can change the value of this attribute for themselves, hidden_value_domain_whitelist (string): Destinations to which a hidden attribute may be sent. Once set, cannot be edited., can (object, read-only): Operations the current user is able to perform on this object }
|
| fields | false | Requested fields. | string | string |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 409 | Resource Already Exists |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 422 | Validation Error |
ValidationError {
message (string, read-only, required): Error details, errors (Array[ValidationErrorDetail], read-only): Error detail array, documentation_url (string, read-only, required): Documentation link }ValidationErrorDetail { field (string, read-only): Field with error, code (string, read-only): Error code, message (string, read-only): Error info message, documentation_url (string, read-only, required): Documentation link }
|
Get User Attribute
GET/api/3.0/user_attributes/{user_attribute_id}
user_attribute(user_attribute_id, fields)
Implementation Notes
Get information about a user attribute.
Response Class
UserAttribute {
id (long, read-only): Unique Id,
name (string): Name of user attribute,
label (string): Human-friendly label for user attribute,
type (string): Type of user attribute ("string", "number", "datetime", "yesno", "zipcode"),
default_value (string): Default value for when no value is set on the user,
is_system (boolean, read-only): Attribute is a system default,
value_is_hidden (boolean): If true, users will not be able to view values of this attribute,
user_can_view (boolean): Non-admin users can see the values of their attributes and use them in filters,
user_can_edit (boolean): Users can change the value of this attribute for themselves,
hidden_value_domain_whitelist (string): Destinations to which a hidden attribute may be sent. Once set, cannot be edited.,
can (object, read-only): Operations the current user is able to perform on this object
}
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| user_attribute_id | true | Id of user attribute | integer | int64 |
| fields | false | Requested fields. | string | string |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
Update User Attribute
PATCH/api/3.0/user_attributes/{user_attribute_id}
update_user_attribute(user_attribute_id, body, fields)
Implementation Notes
Update a user attribute definition.
Response Class
UserAttribute {
id (long, read-only): Unique Id,
name (string): Name of user attribute,
label (string): Human-friendly label for user attribute,
type (string): Type of user attribute ("string", "number", "datetime", "yesno", "zipcode"),
default_value (string): Default value for when no value is set on the user,
is_system (boolean, read-only): Attribute is a system default,
value_is_hidden (boolean): If true, users will not be able to view values of this attribute,
user_can_view (boolean): Non-admin users can see the values of their attributes and use them in filters,
user_can_edit (boolean): Users can change the value of this attribute for themselves,
hidden_value_domain_whitelist (string): Destinations to which a hidden attribute may be sent. Once set, cannot be edited.,
can (object, read-only): Operations the current user is able to perform on this object
}
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| user_attribute_id | true | Id of user attribute | integer | int64 |
| body | true | User Attribute | body |
UserAttribute {
id (long, read-only): Unique Id, name (string): Name of user attribute, label (string): Human-friendly label for user attribute, type (string): Type of user attribute ("string", "number", "datetime", "yesno", "zipcode"), default_value (string): Default value for when no value is set on the user, is_system (boolean, read-only): Attribute is a system default, value_is_hidden (boolean): If true, users will not be able to view values of this attribute, user_can_view (boolean): Non-admin users can see the values of their attributes and use them in filters, user_can_edit (boolean): Users can change the value of this attribute for themselves, hidden_value_domain_whitelist (string): Destinations to which a hidden attribute may be sent. Once set, cannot be edited., can (object, read-only): Operations the current user is able to perform on this object }
|
| fields | false | Requested fields. | string | string |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 422 | Validation Error |
ValidationError {
message (string, read-only, required): Error details, errors (Array[ValidationErrorDetail], read-only): Error detail array, documentation_url (string, read-only, required): Documentation link }ValidationErrorDetail { field (string, read-only): Field with error, code (string, read-only): Error code, message (string, read-only): Error info message, documentation_url (string, read-only, required): Documentation link }
|
Delete User Attribute
DELETE/api/3.0/user_attributes/{user_attribute_id}
delete_user_attribute(user_attribute_id)
Implementation Notes
Delete a user attribute (admin only).
Response Class
None
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| user_attribute_id | true | Id of user_attribute | integer | int64 |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 204 | Successfully deleted. | string |
Get User Attribute Group Values
GET/api/3.0/user_attributes/{user_attribute_id}/group_values
all_user_attribute_group_values(user_attribute_id, fields)
Implementation Notes
Returns all values of a user attribute defined by user groups, in precedence order.
A user may be a member of multiple groups which define different values for a given user attribute. The order of group-values in the response determines precedence for selecting which group-value applies to a given user. For more information, see Set User Attribute Group Values).
Results will only include groups that the caller’s user account has permission to see.
Response Class
array
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| user_attribute_id | true | Id of user attribute | integer | int64 |
| fields | false | Requested fields. | string | string |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
Set User Attribute Group Values
POST/api/3.0/user_attributes/{user_attribute_id}/group_values
set_user_attribute_group_values(user_attribute_id, body)
Implementation Notes
Define values for a user attribute across a set of groups, in priority order.
This function defines all values for a user attribute defined by user groups. This is a global setting, potentially affecting all users in the system. This function replaces any existing group value definitions for the indicated user attribute.
The value of a user attribute for a given user is determined by searching the following locations, in this order:
- the user’s account settings
- the groups that the user is a member of
- the default value of the user attribute, if any
The user may be a member of multiple groups which define different values for that user attribute. The order of items in the group_values parameter determines which group takes priority for that user. Lowest array index wins.
An alternate method to indicate the selection precedence of group-values is to assign numbers to the ‘rank’ property of each group-value object in the array. Lowest ‘rank’ value wins. If you use this technique, you must assign a rank value to every group-value object in the array.
To set a user attribute value for a single user, see Set User Attribute User Value). To set a user attribute value for all members of a group, see Set User Attribute Group Value).
Response Class
array
Parameters
| Parameter | Required? | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| user_attribute_id | true | Id of user attribute | integer | int64 |
| body | true | Array of group values. | body | array |
Response Messages
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 400 | Bad Request |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 404 | Not Found |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 409 | Resource Already Exists |
Error {
message (string, read-only, required): Error details, documentation_url (string, read-only, required): Documentation link }
|
| 422 | Validation Error |
ValidationError {
message (string, read-only, required): Error details, errors (Array[ValidationErrorDetail], read-only): Error detail array, documentation_url (string, read-only, required): Documentation link }ValidationErrorDetail { field (string, read-only): Field with error, code (string, read-only): Error code, message (string, read-only): Error info message, documentation_url (string, read-only, required): Documentation link }
|