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).
You can also add initials fields.
About checkbox fields
A checkbox field is an element that needs to be checked by the participant when processing the document.
When you first add a checkbox field to a document, a checkbox group with a unique ID is automatically created.
Note that you can’t add checkbox 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 checkbox group
In order to add checkboxes to a transaction, you need first to create a checkbox group (unless you send a full transaction request).
To create a checkbox group, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass checkbox_group in the type argument and the checkbox group unique name in the name argument.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=checkbox_group \
-d name=CheckboxGroup1 \
-d minimum_required=1
The API response returns a field sub-object.
{
"id": "fld_w4Dw",
"name": "CheckboxGroup1",
"type": "checkbox_group",
"minimum_required": 1,
"built_in": false,
"updatable": true,
"deletable": true
}
Requirements
- The checkbox group name must be unique within the same document (including radio button groups). If the checkbox group name already exists, the API returns an error.
- If the checkbox group name is not specified, a unique value is automatically assigned.
- The position and size are not available. The checkbox group is not visible in the document.
- Participants are assigned to the whole checkbox group and not to separate checkboxes (this allows us to make sure all checkboxes of a group are assigned to the same participant).
Update a checkbox group
You can update a checkbox 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 checkbox group name in the name argument.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields/fld_w4Dw \
-d name=NewCheckboxGroup1 /
-d minimum_required=1
The API response returns a field sub-object as it was last updated.
{
"id": "fld_w4Dw",
"name": "NewCheckboxGroup1",
"type": "checkbox_group",
"minimum_required": 1,
"built_in": false,
"updatable": true,
"deletable": true
}
Note that you can update a checkbox 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 checkbox
To add a checkbox field to a checkbox group, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass checkbox in the type argument, the checkbox 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=checkbox \
-d parent=CheckboxGroup1 \
-d name=Checkbox1 \
-d page=1 \
-d x=23 \
-d y=20 \
-d checked=false
parent: The checkbox group to which the checkbox is linked identified by itsnameorid.name: The checkbox field unique name. (if not set, a unique value is automatically assigned).page: The page number on which you want to position the checkbox field.x: The checkbox field horizontal coordinate on the document page (in pixels).y: The checkbox field vertical coordinate on the document page (in pixels).checked: If set totrue, the checkbox is already checked when it is added to the transaction document. Default value isfalse.
The API response returns a field sub-object.
{
"id": "fld_qOK0",
"name": "Checkbox1",
"position": {
"page": 1,
"x": 23,
"y": 20,
"width": 24,
"height": 24
},
"type": "checkbox",
"built_in": false,
"checked": false,
"updatable": true,
"deletable": true,
"parent": "fld_w4Dw"
}
Requirements
- The checkbox name must be unique within the same group. If the checkbox name already exixts, the API returns an error.
- If the checkbox name is not specified, a unique value is automatically assigned.
- All checkboxes must be linked to a checkbox group (parent).
- The size of the checkbox is set to 15px x 15px and cannot be edited.
- The checkbox cannot be assigned to a participant (unless you send a full transaction request). Only checkbox groups are assigned to participants.
Update a checkbox
To update a checkbox 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=Checkbox1Beta \
-d parent=NewCheckboxGroup1 \
-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_qOK0",
"name": "Checkbox1Beta",
"position": {
"page": 1,
"x": 50,
"y": 50,
"width": 24,
"height": 24
},
"type": "checkbox",
"built_in": false,
"checked": true,
"updatable": true,
"deletable": true,
"parent": "fld_w4Dw"
}
Requirements
- The checkbox updated name must be unique within the same group. If the checkbox name already exixts, the API returns an error and no changes are saved.
- The checkbox name cannot be updated with a null value, otherwise the API returns an error.
- The checkbox group (parent) name cannot be updated with a null value, otherwise the API returns an error.
- All checkboxes must be linked to a checkbox group (parent).
- The size of the checkbox is set to 15px x 15px and cannot be edited.
Move a checkbox field
You can move a checkbox 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 checkbox field to another page of the same document, the field keeps its original parameters and remains in the same group.
- When you move a checkbox field to another document of the transaction:
- if the target document already contains a checkbox group with the same name as in the original document, the checkbox is added to it and inherits the group’s attributes (such as the assigned signer).
- if the target document has no checkbox group with the same name as in the original document, a new checkbox group is created with the same name as in the original document and the checkbox field is added to it.
Note that you cannot move a checkbox group.
For more details, visit Move a field.
Delete a checkbox / a checkbox group
In order to delete a checkbox group, you need to:
- Unassign the participant assigned to the checkbox group.
- Delete all checkboxes linked to the checkbox group.
- Delete the checkbox group.
Note that you cannot delete a checkbox group if the assigned participant has already performed his/her action (review or signature).
To delete a checkbox or checkbox 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_w4Dw \
-X DELETE
Note that built-in checkbox fields cannot be deleted.
