You may not know the identity of the signer upon the transaction creation. Therefore, you may add an unknown signer to your transaction and assign him/her an editor. The assigned editor needs then to fill the unknown signer requested information (email, full name, phone number).
An unknown participant is identified by his/her designation and a description. The designation is a way to temporarily tag the unknown participant until the editor fills his/her information.
Create a signature/visa field on the document
To create a field, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass the type argument:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=signature
You are returned a field ID in the API response:
{
"id": "fld_a998",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": true
}
Assign an unknown signer to a field
To assign an unknown signer to a field, send a request to POST /v1/transactions/{transaction_id}/signatures and pass the field ID and the unknown signer designation in the request arguments:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d signer=$Designation \
-d field=fld_a998
The unknown participant designation is limited to 250 characters.
Update an unknown participant
You can add a description and set optional parameters to the unknown participant, send a request to POST /v1/transactions/{transaction_id}/participants and pass the unknown participant designation as the email in the request arguments:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/participants \
-d email=$Designation \
-d description=This is a sample description fot the unknown participant. \
-d request_full_name=true \
-d request_phone_name=false
The unknown participant description is limited to 250 characters.
If the request_full_name parameter is set to true, the editor needs to fill the unknown participant full name.
If the request_phone_number parameter is set to true, the editor needs to fill the unknown participant phone number.
Assign an editor to the unknown participant
To assign an editor to the unknown participant, send a request to POST /v1/transactions/{transaction_id}/editions and pass the editor and recipient arguments:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/editors \
-d editor=editor@company.com \
-d recipient=$Designation
Note that the editor can also be known or unknown. However, you need to have at least one known editor to complete the transaction process. If a transaction contains an unknown participant with no assigned known coeditor, it will be stalled as soon as the unknown participant action is ready to be performed. The API returns a stall_reason=unknown_editor.
If the editor refuses to perform his action, the transaction will be stalled and the API returns a stall_reason=edition_refusal.
