Add checkbox 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 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 its name or id.
• 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 to true, the checkbox 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_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:

1. Unassign the participant assigned to the checkbox group.
2. Delete all checkboxes linked to the checkbox group.
3. 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.

---

Add an image field

← Previous

Add radio button fields

Next →