Create custom attributes

This topic describes how to create a custom attribute field or checkbox to gather custom information about companies, users, or leads.

To create a custom attribute field or checkbox,

1. Go to Manage > Reseller > Settings | Custom Attributes. The Custom Attributes page opens.
2. Click Add Custom Attribute above one of the following tables:
   • Company Custom Attributes
   • User Custom Attributes
   • Lead Custom Attributes
     The Add {type} Custom Attribute page appears.
3. Enter the following attribute data information in the corresponding field:
   • Key—Code to uniquely identify this custom attribute. This value becomes the API key used to retrieve the attribute value and also the database column name used in reports.
     This Key cannot be changed after the custom attribute is created.
   • Label—Users see this text above the custom attribute field.
   • Hint—Users see this text-based hint below the custom attribute field. You can use this field to suggest the format of the key. For example, if you are creating a Reseller ID field, and want the format of the key to be reseller-ID, you could use the hint to specify the format using a hyphen instead of an underscore.
4. Select one of the following options from the Input Type drop-down list:
   • Text—Adds a labeled text entry field to the location specified in step 7. If you select this option, continue this procedure with step 5.
   • Checkboxes—Adds a series of checkboxes to the location specified in step 7. When you select this option two additional fields and the Add Option button appear:
     1. Enter a checkbox label and a key for this checkbox in the corresponding fields. Each checkbox must have a unique key to identify the value of the checkbox similar to the key associated with this custom attribute.
     2. Click Add Option. Another pair of Checkbox Label and Key fields appear.
     3. Enter a checkbox label and a key for this checkbox in the corresponding fields.
     4. (Optional) Repeat step b and step c for any additional checkboxes. When the required number of checkboxes are added, continue this procedure with step 6.
5. Select one of the following validation options if you selected Text in step 4:
   • No Validation—The custom field accepts any number of letters, numbers, and special characters.
   • Character Type Validation—Define the validation rule as follows:
     1. Select Alphabetic (the field accepts any combination of characters a - z or A - Z), Numeric (the field accepts any combination of characters 0 - 9), or Alphanumeric (the field accepts any combination of characters a - z, A - Z, or 0 - 9).
     2. (Optional) Enter the maximum number of characters in the Character Count Limit field. For example, if you enter 8, a user cannot enter more than eight characters in the custom attribute field.
     3. (Optional) Select Use exact character count requirement to require that the Character Count Limit that you set (step b) is the only number of characters that a user can enter.
   • External System Validation—Validates the text entered in the custom attribute field against an external system. The external system must include the following in the response:
     • An HTTP status of 200. Any other response is treated as a failure and therefore, an invalid value. For example, a 500 response if the external system is unreachable.
     • For a valid custom attribute, a JSON object containing the field “statusCode” with the value “SUCCESS”.
     • For an invalid custom attribute, a status code value other than “SUCCESS”. You can map the different status codes to an appropriate error message as described in step f.
       Click Configure External Validation and define the validation rules as follows:
     1. Validation URL—This is the external validation endpoint. Enter the external system URL and add the tokens mentioned below:
        • {key}—This resolves to the custom attribute API key.
        • {value}—This resolves to the text the user has entered in the custom attribute field.
        • {type}—(Optional) This resolves to the entity type of the custom attribute. The possible values can be either USER, COMPANY, PURCHASE_ORDER (for Order Custom Attributes), or APPLICATION (for Product Custom Attributes).

     📝 Note: Configuration of external validation URL when setting up the Subscription and Purchase Custom attributes is also available for Checkout V2.
     The text entered in the custom attribute field is passed as a query parameters in the validation URL. For example, you can set the validation URL as the following: https://external-validation-system.com/validate?type={type}&key={key}&value={value}.
     Then, at validation time, the URL queries an OAuth1 supported API endpoint and can be resolved to the following: https://external-validation-system.com/validate?type=COMPANY&key=resellerCompanyIdy&value=576425.
     Note the following in the previous URL example:

     • The type is Company, which is the type of custom attribute that is being validated against the external system.
     • The key is the resellerCompanyId, which was configured on the Add Company Custom Attribute page. This is used to uniquely identify this custom attribute. This value becomes the API key used to retrieve the attribute value.
     • The value is 576425, which is the text entered by the user in the custom attribute field.
     2. (Optional) Authentication type—Select OAuth, which is the type of authentication used to access the remote system.
     3. Consumer Key—Enter the OAuth1 consumer key used to query the external system. This identifies which application is making the request.
     4. Consumer Secret—Enter the OAuth1 consumer secret to query the external system. This is the client password used to authenticate with the server.
     5. Generic Error Message—Enter a simplified message for the user. For example, This is not a valid phone number.
     6. (Optional) Error Messages—Enter a customized error message that maps to the response error codes of the external system. This helps the user understand the error message rather than only seeing a status code. Click Add Error Message in the Error Messages section. Enter your customized error message and the corresponding status code.
        Note: Purchase custom attributes do not support validation.
6. Click Select a location. The Select a location drop-down list appears.
7. Click the Select a location drop-down list, then select the location where you want to add the custom field. The following table shows the location options available depending on the selected type of custom attribute.

Attribute type	Available locations
Company	Checkout (Additional Information and Confirm Order pages) Company Details page Company Signup My Company page Order details modal
User	Checkout (Additional Information and Confirm Order pages) My Profile page Order Details modal User Details page User Signup
Lead	Leads Creation modal Leads Details page

The Role section appears and displays the roles available for the selected attribute type and location. The following table shows the role options available depending on the selected attribute's location.

Attribute location	Available roles
Checkout	Customer Support Reseller Reseller Manager Sales Support User
Company Details page	Customer Support Reseller Reseller Manager Sales Support
Company Signup	Customer Support Reseller Reseller Manager Sales Support User
My Company page	Customer Support Developer Reseller Reseller Manager Sales Support User
Order Details modal	Customer Support Reseller Reseller Manager Sales Support
My Profile page	Customer Support Developer Reseller Reseller Manager Sales Support User
User Details page	Customer Support Reseller Reseller Manager Sales Support
User Signup	Customer Support Reseller Reseller Manager Sales Support User
Product editor	Developer
Product profile	User

8. Select the View and Edit checkboxes next to the user roles that you want to give view or edit permissions to. The permissions apply to this custom attribute field.
9. Select the Required checkbox next to the user roles that must make an entry in this custom attribute field.
10. (Optional) Click Select a location, then repeat steps 6 through 9 to configure additional locations for this custom attribute field.
11. Click Save Changes. The custom attribute field is created and located in the specified locations.