Add radio button fields

A field is the object that bears the action to be performed by a participant. A field has a type which can be either:

• signature (for a signature request by a physical person),
• visa (for a consultation request by a physical person),
• text (for a text field to be filled by the participant),
• label (for a read only text added by the transaction creator on a document),
• checkbox_group (for a group of checkboxes to be checked by the participant),
• checkbox (for a checkbox to be checked by the participant),
• radio_group (for a group of radio buttons to be checked by the participant),
• radiobutton (for a radio button to be checked by the participant),
• dropdown (for a dropdown list where the participant needs to select an option).
• image (for an image field where the participant needs to import an image file),
• signature_date (for a field that displays the date and hour when the participant signed the document),
• full_name (for a field that displays the participant full name),
• email (for a field that displays the participant email),
• company_name (for a field that displays the participant company name),
• job_title (for a field that displays the participant job title).

You can also add initials fields.

About radio button fields

A radio button field is an element that needs to be checked by the participant when processing the document.

When you first add a radio button field to a document, a radio button group with a unique ID is automatically created.

Note that you can’t add radio button fields:

• on a document that has already been processed by a participant,
• on a document that already contains a signature (before being imported to the transaction).

Create a radio button group

In order to add radio buttons to a transaction, you need first to create a radio button group (unless you send a full transaction request).

To create a radio button group, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass radio_group in the type argument and the radio button unique name in the name argument.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=radio_group \
-d name=RadioGroup1 \

The API response returns a field sub-object.

{
 "id": "fld_ekD",
 "name": "RadioGroup1",
 "type": "radio_group",
 "built_in": false,
 "updatable": true,
 "deletable": true,
 "required": true
}

Requirements

• The radio button group name must be unique within the same document (including checkbox groups). If the radio button group name already exists, the API returns an error.
• If the radio button group name is not specified, a unique value is automatically assigned.
• The position and size are not available. The radio button group is not visible in the document.
• Participants are assigned to the whole radio button group and not to separate radio buttons (this allows us to make sure all radio buttons of a group are assigned to the same participant).

Update a radio button group

You can update a radio button group’s name. To do so, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id} and set the new radio button group name in the name argument.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields/fld_w4Dw \
-d name=NewRadioGroup1 /

The API response returns a field sub-object as it was last updated.

{
 "id": "fld_ekD",
 "name": "NewRadioGroup1",
 "type": "radio_group",
 "built_in": false,
 "updatable": true,
 "deletable": true,
 "required": true
}

Note that you can update a radio button group’s name, as long as:

• the assigned participant has not signed yet the document,
• the reviewer has not approved yet the signer’s document.

Add a radio button

To add a radio button field to a radio button group, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass radiobutton in the type argument, the radio button group id or name in the parent argument, as well as position arguments (page, x and y).

You can set other optional arguments.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=radiobutton \
-d parent=RadioGroup1 \
-d name=RadionButton1 \
-d page=1 \
-d x=23 \
-d y=20 \
-d checked=false

• parent: The radio button group to which the radio button is linked identified by its name or id.
• name: The radio button field unique name. (if not set, a unique value is automatically assigned).
• page: The page number on which you want to position the radio button field.
• x: The radio button field horizontal coordinate on the document page (in pixels).
• y: The radio button field vertical coordinate on the document page (in pixels).
• checked: If set to true, the radio button is already checked when it is added to the transaction document. Default value is false.

The API response returns a field sub-object.

{
"id" : "fld_A0Oz",
"name" : "RadioButton1",
"type" : "radiobutton",
"position" : {
"page" : 1,
"x" : 23,
"y" : 20,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_0MMM",
"checked" : false
}

Requirements

• The radio button name must be unique within the same group. If the radio button name already exixts, the API returns an error.
• If the radio button name is not specified, a unique value is automatically assigned.
• All radio buttons must be linked to a radio button group (parent).
• The size of the radio button is set to 15px x 15px and cannot be edited.
• The radio button cannot be assigned to a participant (unless you send a full transaction request). Only radio button groups are assigned to participants.

Update a radio button

To update a radiobutton field, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id} as in the following example.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields/fld_qOK0 \
-d name=NewRadioButton1 \
-d parent=RadioGroup1 \
-d page=1 \
-d x=50 \
-d y=50 \
-d checked=true

The API response returns a field sub-object as it was last updated.

{
"id" : "fld_A0Oz",
"name" : "NewRadioButton1",
"type" : "radiobutton",
"position" : {
"page" : 1,
"x" : 50,
"y" : 50,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_0MMM",
"checked" : true
}

Requirements

• The radio button updated name must be unique within the same group. If the radio button name already exixts, the API returns an error and no changes are saved.
• The radio button name cannot be updated with a null value, otherwise the API returns an error.
• The radio button group (parent) name cannot be updated with a null value, otherwise the API returns an error.
• All radio buttons must be linked to a radio button group (parent).
• The size of the radio button is set to 15px x 15px and cannot be edited.

Move a radio button

You can move a radio button field to another page of the same document or to another document. Send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass the target document in the URL and the field ID you want to move in the move_from argument:

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_aJ4k/fields \
-d move_from=fld_A0Oz

• When you move a radio button field to another page of the same document, the field keeps its original parameters and remains in the same group.
• When you move a radio button field to another document of the transaction:
  • if the target document already contains a radio button group with the same name as in the original document, the radio button is added to it and inherits the group’s attributes (such as the assigned signer).
  • if the target document has no radio button group with the same name as in the original document, a new radio button group is created with the same name as in the original document and the radio button field is added to it.

Note that you cannot move a radio button group.

For more details, visit Move a field.

Delete a radio button / a radio button group

In order to delete a radio button group, you need to:

1. Unassign the participant assigned to the radio button group.
2. Delete all radio buttons linked to the radio button group.
3. Delete the radio button group.

Note that you cannot delete a radio button group if the assigned participant has already performed his/her action (review or signature).

To delete a radio button or radio button group, send a request to DELETE /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}.

curl
https://api.universign.com/v1/transactions/tx_qE67Zr640eVX/documents/doc_bd2a/fields/fld_A0Oz \
-X DELETE

Note that built-in radio button fields cannot be deleted.

---

Add checkbox fields

← Previous

Add dropdown list fields

Next →