Radio buttons enable users to select one (and only one) value from a set of options. In this respect, radio buttons differ from checkboxes. With checkboxes each field is independent from the other fields: a user could, in theory, select all the checkboxes. That’s not the case with radio buttons. For example, suppose you were offering a gift to new users who register for your site: users can receive Gift A, Gift B, or Gift C but not some combination of gifts (e.g., Gift A and Gift B). In a case like that, you would likely use radio buttons, which limit the user to selecting one gift (and one gift only) from the set.

Radio button attributes and terminology

The radio button field, like other Identity Cloud fields, provides a number of attributes that can be used when creating and formatting the field. Also like other Identity Cloud fields, the terminology used to represent these attributes in Console’s Registration Builder sometimes differs from the terminology required when using the Configuration APIs which, in turn, sometimes differs from the terminology used if you view the underlying flow. 

Needless to say, that can be confusing at times. With that in mind, the following table shows the different radio button attributes and how they are referenced in Registration Builder, the Configuration API, and the flow.; click the appropriate link in the flow column for more information about that attribute. Attributes highlighted in yellow are auto-generated when the field is created, and shouldn’t be referenced when making an API call (and can’t be accessed in Registration Builder).

Create radio buttons by using the Configuration API

If you’re using the Configuration APIs to create radio buttons, you must include all the desired attributes and attribute values within the request body of your API call. That request body will look similar to the one shown below (depending, of course, on the number of attributes you use). For example:

{
     "type": "radio",
     "name": "testFieldRadio",
     "schemaAttribute": "primaryAddress.country",
     "ignoreUpdate": false,
     "emptyMeansNull": true,
     "label": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
     },
     "tip": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
     },
     "options": [{
               "selected": true,
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "US"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Canada"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value*: "Mexico"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Iceland",
               "disabled": true
          }
     ]
}

If you’re using Postman, your request body will look like this:

There are at least three things to keep in mind when creating the request body:

• The request body must be formatted using JSON (JavaScript Object Notation). If you get the following error, that often means that your request body isn’t using valid JSON:

  400 Bad Request. The browser (or proxy) sent a request that this server could not understand.
  

• The label and tip attributes must be formatted as JSON objects; that is, you must start with the attribute name (e.g., tip) followed by a colon and a set of curly braces ({ }). Inside those curly braces, use the key member followed by the id of a translation key containing the text you want to use for the label/tip. For example:

  "label": {"key": "352a99f1e9442568706468966749f1e9"}
  

  Note that you must reference a translation key (i.e., a  previously-created piece of text) when creating a label or tip. Suppose you try defining your text within the API call:

  "label": "Employment Status"
  

  That’s going to result in an invalid syntax error. Instead, use the ID of an existing translation key. If you don't have a translation key that uses the string value Employment Status then you'll need to create one before you can create your radio buttons.

• The forms attribute must be formatted as a JSON array, with the form names configured as a comma-separated list between square brackets. For example,

  "forms": ["traditionalRegistrationForm", "socialRegistrationForm"]
  

When creating the individual items for your radio buttons, the following members are available for use:

• label. Value that appears onscreen next to the button. For example, in the radio buttons shown at the beginning of this article, you can see labels such as Full-time Employee and Part-time Employee. This attribute is required.

• value. Value written to the user profile. This can be the same value as the one assigned to the label (e.g., Full-time Employee) or it can be different (for example, the Full-time Employee option could write FT to the user profile). This attribute is required.

• selected. If set to true, indicates the button that selected by default. Note that only one button can have the selected property set to true (which makes sense: you can only have one default value in a collection of radio buttons). Setting  the selected property of multiple items to true causes your API call to fail.

  By default, the selected value is set to false for each button. This attribute is not required.

• disabled. When set to true, the button is “grayed out” and can’t be selected. This attribute is not required.

A complete Curl command for creating a radio button field will look similar to this:

curl -L -X POST \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/fieldExamples/fields' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
  --data-raw '{
     "type": "radio",
     "name": "testFieldRadio",
     "schemaAttribute": "primaryAddress.country",
     "ignoreUpdate": false,
     "emptyMeansNull": true,
     "label": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
       },
     "tip": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
       },
     "options": [{
               "selected": true,
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "US"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Canada"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Mexico"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Iceland",
               "disabled": true
          }
     ]
}'