Last modified on December 17, 2024 at 6:28 pm
Resource URL
Overview
User fields are extra data fields users can fill in when signing up or updating their own account information. Organization administrators have access to an additional set of fields on each user where private data can be recorded. This data is visible to other administrators, and can also be included in reports and data exports, and used as conditions for discounts or message displays.
User-visible data fields are called public; Administrator-only fields are called private. This visibility type is controlled at the User Field Category level, but it is included in all responses that return user fields for clarity.
You can find details of the JSON representation of userfields by referring to the Userfield Object Reference.
Use Case Examples
GET requests
| Operation | Call | Description |
|---|---|---|
| Retrieve all userfields | GET /api/v5/userfields | Retrieve all userfield data. Parameters can be provided to limit the output based on the type of parent category. |
| Retrieve a specific userfield | GET /api/v5/userfields/{id} | Retrieve all userfield data about a specific userfield identified by {id}. |
POST requests
| Operation | Call | Description |
|---|---|---|
| Create text userfield | POST /api/v5/userfields | Create a new userfield where the user may enter freeform text. This field can have minimum and maximum length constraints. |
| Create number userfield | POST /api/v5/userfields | Create a new userfield where the user may enter integer-type numbers. This field can have minimum and maximum value constraints. |
| Create decimal number userfield | POST /api/v5/userfields | Create a new userfield where the user may enter decimal numbers. This field can have minimum and maximum value constraints. |
| Create email userfield | POST /api/v5/userfields | Create a new userfield where the user may enter an email address. This field can have minimum and maximum length constraints, and will have extra validation to ensure the user enters a valid email address. |
| Create date userfield | POST /api/v5/userfields | Create a new userfield where the user choose a date. This field will have a date-picker user interface, and you may define minimum and maximum date constraints. |
| Create dropdown userfield | POST /api/v5/userfields | Create a new dropdown list userfield. You provide a list of options. |
| Create radio-buttons userfield | POST /api/v5/userfields | Create a new radio-buttons userfield. You provide a list of options. |
| Create single checkbox userfield | POST /api/v5/userfields | Create a new checkbox userfield. |
| Create checkboxes userfield | POST /api/v5/userfields | Create a new checkboxes userfield. You provide a list of options. |
| Create true/false userfield | POST /api/v5/userfields | Create a new true/false userfield. This is presented to the user as a dropdown list with True and False as the only two available options. |
| Create yes/no userfield | POST /api/v5/userfields | Create a new yes/no userfield. This is presented to the user as a dropdown list with Yes and No as the only two available options. |
| Create message userfield | POST /api/v5/userfields | Create a new message userfield. This can be used as an informational or instructional message for subsequent userfields. |
PUT requests
Clear all userfield constraintsPUT /dc/api/v5/userfields/{id}Remove all the constraints set on a single userfield
| Operation | Call | Description |
|---|---|---|
| Move userfield to new category | PUT /api/v5/userfields/{id} | You can move a userfield to a different category. Note that this allows you to move a userfield from the private set of admin-only userfield categories into the public user-modifiable categories and vice-versa. |
| Update userfield name | PUT /api/v5/userfields/{id} | Modify the userfield label shown to end-users when they are filling out the information form |
| Toggle userfield required flag | PUT /api/v5/userfields/{id} | Update whether the user will be required to enter a value for this field. If you mark an existing field as required, users will be prompted to enter a value for this field the next time they login. |
| Update userfield options | PUT /api/v5/userfields/{id} | Update the set of choices a user has for option-based inputs like dropdown lists, checkboxes, or radiobuttons |
| Remove a userfield option | PUT /api/v5/userfields/{id} | Remove one of the choices a user has for option-based inputs like dropdown lists, checkboxes, or radiobuttons |
| Update userfield constraints | PUT /api/v5/userfields/{id} | Update the set of constraints on a userfield |
| Remove a userfield constraint | PUT /api/v5/userfields/{id} | Remove a single constraint from a userfield |
| Update message userfield content | PUT /api/v5/userfields/{id} | Update the content of a message-type userfield |
DELETE requests
| Operation | Call | Description |
|---|---|---|
| Delete a custom userfield | DELETE /api/v5/userfields/{id} | Delete a custom userfield from the user info form |