Introduction
Base URLs:
https://api.universign.com (PROD)
https://api.alpha.universign.com (PREPROD)
Universign APIs are organized around REST. They have predictable resource-oriented URLs, accept form-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes, authentication, and verbs. However, if you need to upload a file with your request, you must use a multipart/form-data request type.
Authentication
An authenticated request looks like this:
curl https://api.universign.com/v1/transactions \
-u your_API_key:
Universign uses API keys to authenticate most requests made to the API. To create your API key, you need a Universign account with admin or developer access. Do not hesitate to contact us for further information.
To authenticate your request, you must include your API key in the request header as the value of the username followed by a colon: -u your_API_key: (the password field can be left empty).
Alternatively, you can authenticate via bearer auth as follows: -H "Authorization: Bearer your_API_key".
If you don't provide an API key or provide an invalid one when authentication is required, you will receive a 401 response.
If the API key you provided does not grant you access to the resource, you will receive a 403 response.
Errors
Universign uses conventional HTTP response codes to indicate the success or failure of an API request.
In general, a 200 code indicates success.
Codes in the 4xx range indicate an error caused by input parameters.
Codes in the 5xx range indicate a failure or an unexpected state on Universign infrastructure.
| HTTP code | Description | |
|---|---|---|
| 200 | OK | The operation was successful. |
| 400 | Bad request | The request as you sent it could not be accepted. |
| 401 | Unauthorized | Your API key is invalid or you didn't provide any. |
| 403 | Forbidden | The resource exists and authentication was passed, but your key does not grant you the permission to access it. |
| 404 | Not found | The resource you're trying to access does not exist. |
| 409 | Conflict | The request conflicts with another request. |
| 422 | Unprocessable entity | The request parameters you sent are correct but incompatible with the state of the resource you interact with. |
| 429 | Too many requests | Too many requests have been sent to the API too quickly. |
| 50x | Internal server error | A problem occurred on our side. |
The error object
| Attributes | ||
|---|---|---|
| type | string | The type of error returned among api_connection_error, api_error, authentication_error, invalid_request_error, rate_limit_error. |
| error | string | For errors that can be handled programatically, a short string indicating the error code. Not always present. |
| error_description | string | A human-readable message providing more details about the error. |
| param | string | If the error is parameter-specific, the parameter related to the error. |
Transactions
Transaction endpoints
POST /v1/transactions
GET /v1/transactions/{transaction_id}
POST /v1/transactions/{transaction_id}
POST /v1/transactions/{transaction_id}/start
POST /v1/transactions/{transaction_id}/pause
POST /v1/transactions/{transaction_id}/cancel
GET /v1/transactions
GET /v1/transactions/{transaction_id}/requester-attestation
A transaction is the signature process itself, and the Transaction object is the API resource you interact with, from the creation of a transaction until its termination. Learn more about Universign transactions.
The Transaction object
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is transaction. |
| id | string | The transaction ID. |
| folder_id | string | The folder associated with the transaction, identified by its ID. |
| created_at | date | The date the transaction was created as a draft. Returned format is ISO 8601. |
| started_at | date | The date the draft transaction was started. Returned format is ISO 8601. Displays only if the transaction is no longer in draft. |
| duration | int | The duration of the transaction before it expires, expressed in minutes. Displays only in draft state if no expires_at parameter has been passed. Default value is 20160 (14 days). |
| expires_at | date | The transaction expiration date. Returned format is ISO 8601. |
| closed_at | date | The date the transaction was terminated. Returned format is ISO 8601. Displays only if the transaction state is closed, completed, cancelled or expired. |
| name | string | The transaction name. Default value is the transaction ID. |
| stalled | boolean | Value is true if at least one action is stalled. |
| language | string | The language of the transaction. Returned format is ISO 639-1. fr (French) by default. |
| sender_name_display | string | In whose name the transaction is sent. If the issuing entity feature is activated, possible values are issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). If the issuing entity feature is deactivated, possible values are workspace (the name of the workspace), name_workspace (the name of the person and the name of the workspace), name_email_workspace (the name and email of the person as well as the name of the workspace). Default value is name_email. |
| issuing_entity | object | Information about the issuing entity of the transaction. |
| issuing_entity.id | string | The ID of the issuing entity. |
| issuing_entity.name | string | The name of the issuing entity. |
| issuing-entities.lock_sender_name_display | boolean | Indicates whether the sender name display is locked. |
| creator | object | Information about the creator of the transaction. |
| creator.name | string | The name of the workspace member who created the transaction from the web application. |
| creator.email | string | The email of the workspace member who created the transaction from the web application. |
| creator.workspace_name | string | The name of the workspace which created the transaction by API. |
| creator.api_key_name | string | The name of the API key used to authenticate the transaction creation request. |
| state | string | The transaction state. One of draft, started, paused, cancelled, expired, closed (all participants have completed their action) or completed (the final documents have been extended and are available for download). |
| cancel_code | string | The reason why the transaction was cancelled, among: signature_refusal, review_refusal, consultation_refusal, transaction_refusal, document_not_compliant, other_reason. |
| cancel_reason | string | Details about the reason why you cancel the transaction. |
| participants | array | The list of participants within the transaction. This array is automatically updated when a signer or a reviewer is added to the transaction. |
| participants[ ].email | string | The email address of the participant. |
| participants[ ].designation | string | The designation of the unknown participant. Max 250 characters. |
| participants[ ].description | string | The description of the unknown participant. Max 250 characters. |
| participants[ ].invitation_subject | string | The subject of the participant's invitation email. Max 100 characters. |
| participants[ ].invitation_message | string | The participant's invitation message. Max 1000 characters. |
| participants[ ].reminder_subject | string | The subject of the participant's reminder email. Max 100 characters. |
| participants[ ].reminder_message | string | The participant's reminder message. Max 1000 characters. |
| participants[ ].signed_documents_subject | string | The subject of the email sent to the participant when signed documents are available. Max 100 characters. |
| participants[ ].signed_documents_message | string | The message sent to the participant when signed documents are available. Max 1000 characters. |
| participants[ ].name_constraint | string | The participant full name that must be used in the transaction. (Deprecated) See full_name and full_name_type. |
| participants[ ].fullname_prerequisite | string | The participant full name that must be used in the transaction. (Deprecated) See full_name and full_name_type. |
| participants[ ].fullname_suggestion | string | The participant full name suggestion that can be used in the transaction. (Deprecated) See full_name and full_name_type. |
| participants[ ].full_name | string | The participant full name as it will display in the signature. |
| participants[ ].full_name_type | string | The participant's full name type. One of suggestion or prerequisite. |
| participants[ ].request_full_name | boolean | Value is true if the full name of the unknown participant is requested. |
| participants[ ].phone_number_flex_constraint | string | The participant mobile number that must be used for authentication when the minimum requested signature level is level1. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number_flex_prerequisite | string | The participant mobile number that must be used for authentication when the minimum requested signature level is level1. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number_suggestion | string | The participant mobile number that is suggested for authentication, but can be modified by the participant (or by Universign if the participant owns a certificate linked to a different mobile number.). (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number | string | The participant mobile number that is used for authentication. |
| participants[ ].phone_number_type | string | The participant's mobile number type. One of suggestion, flex_prerequisite or prerequisite. |
| participants[ ].request_phone_number | boolean | Value is true if the phone number of the unknown participant is requested. |
| participants[ ].stall_trigger | int | The allotted time, expressed in hours, for the participant to complete his/her action, from the moment his/her action is open. If the participant is still inactive after that period, the participant action is flagged as stalled and so is the transaction. |
| participants[ ].ongoing_conversation | boolean | Whether there is an ongoing conversation between the participant and the transaction creator. |
| participants[ ].has_unread_message | boolean | Whether there is at least one unread message in the conversation. Can be true only if ongoing_conversation is true. |
| participants[ ].schedule | array of int | The emailing schedule of the participant, expressed in hours. |
| participants[ ].do_not_invite_before | date | The date and time after which the invitation is sent to the participant. |
| participants[ ].min_signature_level | string | The minimum required level of signature for a participant among: level0 (simple signature without authentication), level1 (simple signature), level2 (advanced signature), level3(advanced signature with qualified certificate) and level4 (qualified signature). |
| participants[ ].waiting_period | number | The duration in days of the reflection period before the participant can sign his/her documents. |
| participants[ ].signature_image_reference | string | The reference of the custom signature image displayed on the signature cartridge. |
| sealers | array of objects | The list of sealers. |
| sealers[].id | string | The sealer ID. |
| sealers[].name | string | The sealer name. |
| documents | array of objects | The documents added to the transaction. |
| documents[ ].id | string | The document ID. |
| documents[ ].name | string | The name of the document, if you set any. If not, the file name is used. |
| documents[ ].updatable | boolean | Whether the document is currently updatable or not. |
| documents[ ].deletable | boolean | Whether the document is currently deletable or not. |
| documents[ ].fields | array of objects | The list of all fields associated with the document. |
| documents[ ].fields[ ].id | string | The field ID. |
| documents[ ].fields[ ].name | string | The name of the field. |
| documents[ ].fields[ ].type | string | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| documents[ ].fields[ ].built_in | boolean | Whether the field is built-in the PDF. |
| documents[ ].fields[ ].consents | array of strings | Mandatory consents to agree to when signing or reading the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| documents[ ].fields[ ].optional_consents | array of strings | Optional consents to agree to when signing or reading the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| documents[ ].fields[ ].updatable | boolean | Whether the field is currently updatable or not. |
| documents[ ].fields[ ].deletable | boolean | Whether the field is is currently deletable or not. |
| documents[ ].fields[ ].position | object | The position of the field on the document. |
| documents[ ].fields[ ].position.page | int | The page number on which the field is positioned. |
| documents[ ].fields[ ].position.x | int | The field horizontal coordinate on the document page (in pixels). |
| documents[ ].fields[ ].position.y | int | The field vertical coordinate on the document page (in pixels). |
| documents[ ].fields[ ].position.height | int | The height of the field (expressed in PDF's default user space units). Displays only if field type is text, label or dropdown. If not provided, the height is set to font height. Default value is 19. |
| documents[ ].fields[ ].position.width | int | The width of the field (expressed in PDF's default user space units). Displays only if field type is text, label or dropdown. Default value is 200. |
| documents[ ].fields[ ].font_size | number | The font size of the field content. Possible values between 7 and 12. Default value is 12. |
| documents[ ].fields[ ].max_length | number | The max length of the field content. Displays only if field type is text. |
| documents[ ].fields[ ].tooltip | string | Tooltips about the text the participant needs to add to the document during signature process. Displays only if field type is text. |
| documents[ ].fields[ ].value | string | Displays only if field type is label or dropdown. If field type is label, it is the text you want to display in the label field. If field type is dropdown, it is the value of the dropdown option that will be selected by default for the dropdown list. |
| documents[ ].fields[ ].alignment | string | The alignment of initial fields content. Displays only for initials-fields. |
| documents[ ].fields[ ].checked | boolean | Whether the checkbox or radio button field is already checked or not. Displays only if field type is checkbox or radiobutton. |
| documents[ ].fields[ ].minimum_required | int | The minimum number of checkboxes to be checked by the participant. Displays only if field type is checkbox_group. |
| documents[ ].fields[ ].parent | string | The ID of the parent checkbox or radio button group. Displays only if field type is checkbox or radiobutton. |
| documents[ ].fields[ ].required | boolean | Whether the participant must choose a dropdown option or not. Displays only if field type is dropdown. |
| documents[ ].fields[ ].options | array | The list of dropdown list options. The key-value pairs of this list represent the key-value pairs of the dropdown list options. Displays only if field type is dropdown. |
| instructions | object | The signature and review instructions for the transaction. Used to link a signer to a field and a reviewer to a participant. Instructions are automatically updated when a signer or a reviewer is added to the transaction. |
| instructions.signatures | array | Instructions linked to signatures and visas. |
| instructions.signatures[ ].signer | string | The signer's email address or designtation (in case the participant is unknown). |
| instructions.signatures[ ].field | string | The field that bears the signature or visa instruction, designated by its ID. |
| instructions.reviews | array | Instructions linked to reviews. |
| instructions.reviews[ ].reviewer | string | The reviewer's email address. |
| instructions.reviews[ ].recipient | string | The email address of the participant for whom the review is intended. |
| instructions.sequencing | array | Sequencing instructions between participants. |
| instructions.sequencing[ ].before | string | The participant (identified by his/her email) who must perform his/her action before the after participant. |
| instructions.sequencing[ ].after | string | The participant (identified by his/her email) who must perform his/her action after the before participant. |
| instructions.editions | array | Instructions linked to editions. |
| instructions.editions[ ].editor | string | The editor's email address or designation (in case s/he is unknown). |
| instructions.editions[ ].recipient | string | The reference of the unknown participant to be edited. |
| instructions.captures | array | Instructions linked to captures. |
| instructions.captures[ ].actor | The email of the participant who must provide documents. | |
| instructions.captures[ ].document_type | string | The type of document that is requested, among identity_document, iban, address_proof, tax_statement and other. |
| instructions.captures[ ].accepted_identity_documents | array of strings | If the document_type is identity_document, the list of accepted identity documents. |
| instructions.captures[ ].total_items_required | int | The total number of identity documents that are expected to be provided by the participant, among the list of accepted_identity_documents. |
| instructions.captures[ ].covered_period | int | If document_type is tax_statement, this is the covered period you want the participant to provide. 1 for last year, 2 for last two years, 3 for last three years, 4 for last four year and 5 for last five years. Default value is 2. |
| instructions.captures[ ].name | string | If document_type is other, this is the name of the document you want the participant to provide. |
| instructions.captures[ ].tag | string | If you requested the same document_type value more than once for the same actor, the tag differenciates each request. |
| instructions.captures[ ].guideline | string | Additional information for the participant. |
| actions | array | The list of actions to perform. The actions array is automatically updated when a signer or a reviewer is added to the transaction. |
| actions[ ].id | string | The action ID. |
| actions[ ].actor | string | The email address of the participant having to perform the action. |
| actions[ ].state | string | The state of the action, amongst open (the participant can perform his/her action), waiting (the participant cannot perform his/her action yet) or closed (the action is completed). Please note that an action can be reopened after it was closed: this happens if the transaction is updated dynamically with new instructions for the actor. |
| actions[ ].started_at | date | The date the action has been opened for its actor. |
| actions[ ].closed_at | date | The date the action has been closed or its actor (meaning there are no more tasks to perform). Please note that the date value can change if the transaction is updated dynamically with new instructions for the actor. |
| actions[ ].url | url | The URL to the participant's action page. |
| actions[ ].tasks | array | The tasks list the participant must complete before the action is closed. |
| actions[ ].tasks[ ].type | string | The task type. Value is signature for a signature or visa task, or review for a review task. |
| actions[ ].tasks[ ].state | string | The state of the task. Can be todo (the participant can perform the requested task), skipped (the task no longer needs to be performed) or done (the participant has performed the requested task). |
| actions[ ].tasks[ ].field | string | The field ID, if the action type is signature. |
| actions[ ].tasks[ ].recipient | string | The recipient of the review, if the action type is review. |
| actions[ ].stalled | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| actions[ ].document_type | string | The type of document that must be provided by the participant. |
| actions[ ].tag | string | If you requested the same document_type value more than once for the same actor, the tag differenciates each request. |
| actions[ ].editor | string | The editor of the participant, if the action type is edition. |
| metadata | object | The list of metadata. The key-value pairs of this object represent the key-value pairs of the transaction's metadata. |
| metadata.* | string | The metadata entries you associated with the transaction. |
| carbon_copies | array of strings | The emails you want to notify and give access to signed documents when the transaction is completed. |
| carbon_copy_subject | string | The subject of the carbon copy notification email. Max 100 characters. |
| carbon_copy_message | string | The carbon copy notification message. Max 1000 characters. |
| watchers | array of strings | Workspace members who follow the transaction, identified by their emails. |
| watchers[ ].member_id | string | The watcher's member id. |
| watchers[ ].email | string | The watcher's email. |
| watchers[ ].full_name | string | The watcher's full name. |
| uploads | array | If you requested a capture, the list of documents uploaded by the participant. |
| uploads[ ].actor | string | The actor of the captured document. |
| uploads[ ].captured_documents | array | Information about the captured documents. |
| uploads[ ].captured_documents[ ].id | string | The captured document id. |
| uploads[ ].captured_documents[ ].document_type | string | The type of the captured document. |
| uploads[ ].captured_documents[ ].captured_at | string | The capture date. |
| uploads[ ].captured_documents[ ].name | string | The name of the captured document. |
| uploads[ ].captured_documents[ ].tag | string | The tag of the captured document. |
| uploads[ ].captured_documents[ ].tax_year | number | The captured document's tax year(s). |
| uploads[ ].captured_documents[ ].accepted_identity_documents | array | The capture’s accepted identity documents. |
| collected | array | The list of done actions related to consents. |
| collected[ ].actor | string | The email address of the actor who performed the consent action. |
| collected[ ].documents | array | The list of documents involved in the consent action. |
| collected[ ].documents[ ].id | string | The document's id. |
| collected[ ].documents[ ].granted_consents | array | The agreed consents of the signature fields in this document. |
| collected[ ].documents[ ].ungranted_consents | array | The non-agreed consents of the signature fields in this document. |
| private | boolean | Whether the transaction is private or not. A private transaction can only be seen by its creator and members with admin rights. |
Create a transaction
POST /v1/transactions
To start a signature process, you need to create a transaction. Although a simple POST to the /transactions endpoint is enough to create a draft transaction, you can already set a few parameters by passing the following optional arguments:
Request example
curl https://api.universign.com/v1/transactions \
-d name=MyTransaction \
-d duration=4320
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | optional | The transaction name. By default, the transaction ID is used. Max 100 characters. |
| language | string | optional | The language of the transaction. This parameter defines the language of the emails sent to participants and the language of the signature page. Expected input format is ISO 639-1. We currently support 11 languages: Bulgarian (bg), Catalan (ca), Dutch (nl), English (en), French (fr), German (de), Italian (it), Polish (pl), Portuguese (pt), Romanian (ro) and Spanish (es). French (fr) is the default language. |
| duration | int | optional | The required duration of the transaction before it expires, expressed in minutes. Default value is 20160 (14 days) and maximum value is 86400 (60 days) or 259200 (180 days) depending on whether long-term transactions are enabled or not on your Workspace. Note that the countdown to expiration starts when the transaction is started, not when it is created as a draft. Do not pass this parameter if you pass the expires_at parameter. |
| expires_at | date | optional | The required expiration date of the transaction. Expected input format is ISO 8601 (ex: 2021-10-14T17:32Z). The maximum duration of a transaction being 60 or 180 days, you can set its expiry date to current date + 67 or 187 days depending on the workspace entitlements (the 7 extra days correspond to the maximum period in draft state. Do not pass this parameter if you pass the duration parameter. |
| folder_id | string | optional | The folder in which you want to create the transaction, identified by its ID. By default, the transaction is created in the workspace default folder. |
| metadata[*] | string | optional | To add a metadata to the transaction, you must specify it as a key-value pair. The value of the metadata key must be appended to the metadata field between brackets (for example metadata[doc_type]), and must not exceed 20 characters. Please note that square brackets ([ or ]), equal sign (=), plus sign (+) and underscore (_) and are unsupported characters in the value of the metadata key. The metadata variable must be passed as the value and must not exceed 200 characters (for example contract). You can pass up to 15 metadata entries. |
| carbon_copies | array of strings | optional | The emails you want to notify and give access to signed documents when the transaction is completed. |
| carbon_copy_subject | string | optional | The subject of the carbon copy notification email. Max 100 characters. |
| carbon_copy_message | string | optional | The carbon copy notification message. Max 1000 characters. We support text format or xml with authorized xhtml tags only. For more details, refer to add someone in copy. |
| private | boolean | optional | Set to true if you want the transaction to be seen only by you and members with admin rights. Default value depends on your workspace preferences. |
| watchers | array of strings | optional | Workspace members you want them to follow the transaction, identified by their emails. |
| issuing_entity_id | string | optional | The ID of the issuing entity of the transaction. If you dont set the issuing_entity_id, the transaction will be sent on behalf of your workspace default issung entity. |
| sender_name_display | string | optional | In whose name the transaction is sent. If the issuing entity feature is activated, possible values are issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). If the issuing entity feature is deactivated, possible values are workspace (the name of the workspace), name_workspace (the name of the person and the name of the workspace), name_email_workspace (the name and email of the person as well as the name of the workspace). Default value is name_email. When the transaction is created by API, the only possible values are workspace or issuing_entity. |
Returns
The API returns a draft transaction object.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "MyTransaction",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "fr",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ ],
"instructions" : {
"signatures" : [ ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"max_expiry" : "180_days",
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Retrieve a transaction
GET /v1/transactions/{transaction_id}
This endpoint enables you to retrieve information about a specific transaction initiated by your workspace.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy
Returns
The API returns transaction object, as it was last updated.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "MyTransaction",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "fr",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ ],
"instructions" : {
"signatures" : [ ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"max_expiry" : "180_days",
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Update a transaction
POST /v1/transactions/{transaction_id}
This endpoint enables you to update the following transaction parameters. Note that you can only update a transaction in draft, started, stalled or paused state.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy \
-d name=NewName \
-d language=en
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | optional | The transaction name. By default, the transaction ID is used. The transaction name can be updated until a participant action.task is done. Max 100 characters. |
| language | string | optional | The language of the transaction. This parameter defines the language of the emails sent to participants and the language of the signature page. Expected input format is ISO 639-1. We currently support 11 languages: Bulgarian (bg), Catalan (ca), Dutch (nl), English (en), French (fr), German (de), Italian (it), Polish (pl), Portuguese (pt), Romanian (ro) and Spanish (es). French (fr) is the default language. |
| duration | int | optional | The required duration of the transaction before it expires, expressed in minutes. Default value is 20160 (14 days) and maximum value is 86400 (60 days) or 259200 (180 days) depending on whether long-term transactions are enabled or not on your Workspace. Note that the countdown to expiration starts when the transaction is started, not when it is created as a draft. Do not pass this parameter if you pass the expires_at parameter. |
| expires_at | date | optional | The required expiration date of the transaction. Expected input format is ISO 8601 (ex: 2021-10-14T17:32Z). The maximum duration of a transaction being 60 or 180 days, you can set its expiry date to current date + 67 or 187 days depending on the workspace entitlements days (the 7 extra days correspond to the maximum period in draft state. Do not pass this parameter if you pass the duration parameter. |
| folder_id | string | optional | The folder in which you want to put the transaction, identified by its ID. |
| metadata[*] | string | optional | To add a metadata to the transaction, you must specify it as a key-value pair. The value of the metadata key must be appended to the metadata field between brackets (for example metadata[doc_type]), and must not exceed 20 characters. Please note that square brackets ([ or ]), equal sign (=), plus sign (+) and underscore (_) and are unsupported characters in the value of the metadata key. The metadata variable must be passed as the value and must not exceed 200 characters (for example contract). You can pass up to 15 metadata entries. |
| carbon_copies | array of strings | optional | The emails you want to notify and give access to signed documents when the transaction is completed. |
| carbon_copy_subject | string | optional | The subject of the carbon copy notification email. Max 100 characters. |
| carbon_copy_message | string | optional | The carbon copy notification message. Max 1000 characters. We support text format or xml with authorized xhtml tags only. For more details, refer to add someone in copy. |
| private | boolean | optional | Set to true if you want the transaction to be seen only by you and members with admin rights. Default value depends on your workspace preferences. |
| watchers | array of strings | optional | Workspace members you want them to follow the transaction, identified by their emails. |
| issuing_entity_id | string | optional | The ID of the issuing entity of the transaction. If you dont set the issuing_entity_id, the transaction will be sent on behalf of your workspace default issung entity. |
| sender_name_display | string | optional | In whose name the transaction is sent. If the issuing entity feature is activated, possible values are issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). If the issuing entity feature is deactivated, possible values are workspace (the name of the workspace), name_workspace (the name of the person and the name of the workspace), name_email_workspace (the name and email of the person as well as the name of the workspace). Default value is name_email. When the transaction is created by API, the only possible values are workspace or issuing_entity. |
| evidence_archiving_configuration_id | string | optional | The ID of the evidence files archiving configuration. To be retrieved from your workspace. For more information about archiving configuration, refer to Archive evidence file. |
| delete_evidence_archiving_configuration_id | boolean | optional | Set to true if you want your evidence files to be archived only through our internal archiving system. Do not pass this parameter if you pass the evidence_archiving_configuration_id parameter. |
Returns
The API returns a transaction object, updated with the values you entered as request parameters.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ ],
"instructions" : {
"signatures" : [ ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"max_expiry" : "180_days",
"private" : false
}
Start a transaction
POST /v1/transactions/{transaction_id}/start
Once a transaction contains at least one signature instruction (i.e a document with a field and a signer), it can be started. Once a transaction is started, all participants that are first in the queue can perform their action.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/start \
-X POST
Returns
The API returns a transaction object with a started_at date. Once the transaction is started, you can still update it dynamically, as long as your requests are compatible with either the state of the resource or sub-resource you interact with, and coherent with the signature flow. For example, it is not possible to change a document name after the document has been signed. Nor is it possible to update a signer's details once s/he has signed.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"started_at" : "2024-10-08T08:25:06Z",
"expires_at" : "2024-10-11T08:25:06Z",
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "started",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"request_full_name" : false,
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"invitation_message" : "SampleMessage",
"schedule" : [ ],
"ongoing_conversation" : true,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 7
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ {
"actor" : "jane@universign.com",
"document_type" : "identity_document",
"accepted_identity_documents" : [ "passport", "identity_card" ],
"total_items_required" : 2,
"guideline" : "Black"
}, {
"actor" : "jane@universign.com",
"document_type" : "address_proof",
"guideline" : "document"
}, {
"actor" : "jane@universign.com",
"document_type" : "iban",
"tag" : "personal",
"guideline" : "please"
}, {
"actor" : "jane@universign.com",
"document_type" : "iban",
"tag" : "spouse",
"guideline" : "please"
}, {
"actor" : "jane@universign.com",
"document_type" : "tax_statement",
"covered_period" : 3
}, {
"actor" : "jane@universign.com",
"document_type" : "other",
"tag" : "vitale",
"name" : "carte_vitale"
} ],
"sequencing" : [ {
"before" : "jane@universign.com",
"after" : "jean@universign.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "address_proof"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "iban",
"tag" : "personal"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "iban",
"tag" : "spouse"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "other",
"tag" : "vitale"
} ],
"stalled" : false
}, {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : true,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"max_expiry" : "180_days",
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Pause a transaction
POST /v1/transactions/{transaction_id}/pause
It is possible to pause a transaction. This is particularly useful if you wish to safely edit a transaction that has already been started (although not mandatory), or if you want to prevent a participant from accessing the signature page momentarily.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/pause \
-X POST
Returns
The API returns a transaction object with a paused state. Although participants will no longer be able to access a paused transaction nor receive notifications, please note that pausing a transaction does not affect its expiration. If you wish to postpone the transaction expiration date, you need to do so by updating the transaction (note that a transaction duration cannot exceed 45 days after it is started).
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"started_at" : "2024-10-08T08:25:06Z",
"expires_at" : "2024-10-11T08:25:06Z",
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "paused",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"request_full_name" : false,
"full_name_type" : "suggestion"
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"invitation_message" : "SampleMessage",
"schedule" : [ ],
"ongoing_conversation" : true,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 7,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ {
"actor" : "jane@universign.com",
"document_type" : "identity_document",
"accepted_identity_documents" : [ "passport", "identity_card" ],
"total_items_required" : 2,
"guideline" : "Black"
}, {
"actor" : "jane@universign.com",
"document_type" : "address_proof",
"guideline" : "document"
}, {
"actor" : "jane@universign.com",
"document_type" : "iban",
"tag" : "personal",
"guideline" : "please"
}, {
"actor" : "jane@universign.com",
"document_type" : "iban",
"tag" : "spouse",
"guideline" : "please"
}, {
"actor" : "jane@universign.com",
"document_type" : "tax_statement",
"covered_period" : 3
}, {
"actor" : "jane@universign.com",
"document_type" : "other",
"tag" : "vitale",
"name" : "carte_vitale"
} ],
"sequencing" : [ {
"before" : "jane@universign.com",
"after" : "jean@universign.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"started_at" : "2024-10-08T08:25:06Z",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "address_proof"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "iban",
"tag" : "personal"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "iban",
"tag" : "spouse"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "other",
"tag" : "vitale"
} ],
"stalled" : false
}, {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : true,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"max_expiry" : "180_days",
"private" : false
}
Cancel a transaction
POST /v1/transactions/{transaction_id}/cancel
This endpoint enables you to cancel a transaction. Only draft, started or paused transactions can be cancelled.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/cancel \
-X POST
| Arguments | Type | Description | |
|---|---|---|---|
| cancel_code | string | optional | The reason why you cancel the transaction, if you want to state any. Accepted values are signature_refusal, review_refusal, consultation_refusal, transaction_refusal, document_not_compliant, other_reason. Note that if the cancellation is due to a participant's action refusal, the system returns whether the participant refused a document to sign, to review, or to read or if the refusal relates to the whole transaction, so that you can use this information as your cancel code. This information is available as the message_type value returned by the API in the participant conversation. |
| cancel_reason | string | optional | Details about the reason why you cancel the transaction. Max 250 characters. |
Returns
The API returns a transaction object with a cancelled state and a cancel_code if you specified one. If you try to cancel a transaction with any other state than draft, startedor paused, you are returned an API error. Please note that cancelled transactions are permanently deleted from the system after 60 days. Also, note that it is not possible to download documents from a cancelled transaction, even if they have been signed partially.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"started_at" : "2024-10-08T08:25:06Z",
"closed_at" : "2024-10-08T08:25:08Z",
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "cancelled",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"request_full_name" : false,
"full_name_type" : "suggestion"
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"invitation_message" : "SampleMessage",
"schedule" : [ ],
"ongoing_conversation" : true,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 7,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ {
"actor" : "jane@universign.com",
"document_type" : "identity_document",
"accepted_identity_documents" : [ "passport", "identity_card" ],
"total_items_required" : 2,
"guideline" : "Black"
}, {
"actor" : "jane@universign.com",
"document_type" : "address_proof",
"guideline" : "document"
}, {
"actor" : "jane@universign.com",
"document_type" : "iban",
"tag" : "personal",
"guideline" : "please"
}, {
"actor" : "jane@universign.com",
"document_type" : "iban",
"tag" : "spouse",
"guideline" : "please"
}, {
"actor" : "jane@universign.com",
"document_type" : "tax_statement",
"covered_period" : 3
}, {
"actor" : "jane@universign.com",
"document_type" : "other",
"tag" : "vitale",
"name" : "carte_vitale"
} ],
"sequencing" : [ {
"before" : "jane@universign.com",
"after" : "jean@universign.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"started_at" : "2024-10-08T08:25:06Z",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "address_proof"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "iban",
"tag" : "personal"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "iban",
"tag" : "spouse"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "tax_statement"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "other",
"tag" : "vitale"
} ],
"stalled" : false
}, {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : true,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"max_expiry" : "180_days",
"private" : false
}
List all transactions
GET /v1/transactions
This endpoint enables you to retrieve all the transactions initiated by your workspace that you have the permission to edit and/or view and pass a series of optional filters to refine you request.
Request example
curl https://api.universign.com/v1/transactions?size=1
| Arguments | Type | Description | |
|---|---|---|---|
| size | int | optional | The number of transactions you want to retrieve, starting from the most recent. Maximum is 100, default is 50. |
| ending_before | string | optional | Expected value is a transaction ID. Use for pagination to return the transactions listed before the specified transaction. Do not pass if you set the starting_after parameter. |
| starting_after | string | optional | Expected value is a transaction ID. Use for pagination to return the transactions listed after the specified transaction. Do not pass if you set the ending_before parameter. |
| folder_id | string | optional | Returns only transactions associated with this folder ID. |
| creator | string | optional | Expected value is an email address. Returns only transactions created by the workspace member associated with this email. |
| creator_api_key_id | string | optional | Expected value is an API key ID. Returns only transactions created by the API key that authenticated the transaction API request. |
| created_gt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns only transactions created at and after the specified date. |
| created_lt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns only transactions created at and before the specified date. |
| expires_soon | boolean | optional | If true, returns only transactions which expire less than 48h after the current date. |
| text_search | string | optional | Returns transactions that contain the specified string in one of: transaction name, transaction ID, participant name, participant email, document name, seal ID, seal name and metadata values. To search for a string that starts with a specific string, append ^ to the value (example: ^john will retrieve all occurences starting with john. |
| state | string | optional | Returns only transactions with the requested state. One of draft, started, paused, cancelled, expired, closed or completed. |
| stalled | boolean | optional | Returns only transactions that are flagged stalled. |
| private | boolean | optional | Returns only private transactions. |
| issuing_entity_id | string | optional | Returns only transactions created by a given issuing entity. |
| waiting_period | boolean | optional | Returns only transactions with a reflection period. |
Returns
The API returns the list of all transactions matching your request. The response description is as follows:
Response example
{
"has_more" : true,
"content" : [ {
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"state" : "draft",
"metadata" : { },
"participants" : [ ],
"sealers" : [ ],
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"watchers" : [ ],
"origin" : "API",
"creator" : {
"api_key_id" : "apk_AvLZnED1PGJE",
"workspace_name" : "DemoWS"
},
"max_expiry" : "180_days",
"private" : false
} ]
}
| Parameters | Type | Description |
|---|---|---|
| has more | boolean | If there are more existing transactions in the workspace than the transactions returned in the response. |
| content | string | The list of transactions. |
| content[ ].object | string | The object's type. Value is transaction. |
| content[ ].id | string | The transaction ID. |
| content[ ].folder_id | string | The ID of the folder associated with the transaction. |
| content[ ].folder_name | string | The name of the folder associated with the transaction. |
| content[ ].created_at | date | The transaction creation date. Returned format is ISO 8601. |
| content[ ].started_at | date | The transaction start date, if the transaction is started. Returned format is ISO 8601. |
| content[ ].completed_at | date | The transaction completion date, if the transaction is completed. Returned format is ISO 8601. |
| content[ ].expires_at | date | The transaction expiry date, if the transaction is started. Returned format is ISO 8601. |
| content[ ].name | string | The transaction name. |
| content[ ].stalled | boolean | Whether there is an ongoing alert on the transaction. |
| content[ ].state | string | The transaction state. One of draft, started, paused, cancelled, completed, archived, expired. |
| content[ ].metadata | object | The list of metadata. The key-value pairs of this object represent the key-value pairs of the transaction's metadata. |
| content[ ].metadata.* | string | The metadata entries you associated with the transaction. |
| content[ ].participants | array | The list of participants. |
| content[ ].participants[ ].email | string | The participant email. |
| content[ ].participants[ ].state | string | The participant state. One of open or completed. |
| content[ ].participants[ ].name_constraint | string | The participant full name used in the transaction. (Deprecated) See full_name and full_name_type. |
| content[ ].participants[ ].fullname_prerequisite | string | The participant full name used in the transaction. (Deprecated) See full_name and full_name_type. |
| content[ ].participants[ ].full_name | string | The participant full name as it will display in the signature. |
| content[ ].participants[ ].full_name_type | string | The participant's full name type. One of suggestion or prerequisite. |
| content[ ].participants[ ].waiting_period | number | The duration in days of the reflection period before the participant can sign his/her documents. |
| content[ ].sealers | array | The list of seals. |
| content[ ].sealers[ ].id | string | The moral person's certificate ID. |
| content[ ].sealers[ ].name | string | The seal common name. |
| content[ ].progress_value | int | The progression of the transaction in percent. Value is between 0 and 100. |
| content[ ].ongoing_conversation | boolean | If true, means there is an ongoing conversation between at least one participant and the workspace. |
| content[ ].has_unread_message | boolean | If true, means there is at least one unread message from a participant within the transaction. |
| content[ ].creator | object | Information regarding the creator of the transaction. |
| content[ ].creator.name | string | The full name of the person who created the transaction, if the transaction was created via the web application. |
| content[ ].creator.email | string | The email of the person who created the transaction, if the transaction was created via the web application. |
| content[ ].creator.workspace | string | The workspace that initiated the transaction. |
| content[ ].creator.api_key_id | string | The ID of the API key that authenticated the transaction API request. |
| content[ ].watchers | array | The list of watchers for a transaction. |
| content[ ].watchers[ ].member_id | string | The watcher's member id. |
| content[ ].watchers[ ].email | string | The watcher's email. |
| content[ ].watchers[ ].full_name | string | The watcher's full name. |
Retrieve the requester attestation for cancelled and expired transactions
GET /v1/transactions/{transaction_id}/requester-attestation
This endpoint enables you to download requester attestations only for cancelled and expired transactions.
Note that requester attestations are not provided for transactions which were in draft state before being cancelled.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/requester-attestation?=lang=fr
| Arguments | Type | Description | |
|---|---|---|---|
| lang | string | optional | The language of the requester attestation. Expected input format is ISO 639-1. We currently support 11 languages: Bulgarian (bg), Catalan (ca), Dutch (nl), English (en), French (fr), German (de), Italian (it), Polish (pl), Portuguese (pt), Romanian (ro) and Spanish (es). Default value is the language of the transaction. |
Returns
The API returns the PDF requester attestation.
Transaction documents & fields
Transaction documents and fields endpoints
POST /v1/transactions/{transaction_id}/documents[POST /v1/transactions/{transaction_id}/documents/{document_id]](#update_document)
DELETE /v1/transactions/{transaction_id}/documents/{document_id}
POST /v1/transactions/{transaction_id}/documents/{documents_id}/revoke-download
POST /v1/transactions/{transaction_id}/documents/{document_id}/fields
POST /v1/transactions/{transaction_id}/documents/{document_id}/initials-fields
POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}
DELETE /v1/transactions/{transaction_id}/fields/{field_id}
Add a document to a transaction
Adding a document to a transaction is a two-step process that consists of:
1. uploading your file to https://api.universign.com/v1/files, which generates a file ID.
2. adding the file ID to your request.
Upload the file to Universign
POST /v1/files
Before you can add your document to the transaction, you must upload it to Universign using a multipart/form-data request. Note that you must upload only one file per request.
Request example
curl https://api.universign.com/v1/files
-F file=@DocumentTest.pdf
| Arguments | Type | Description | |
|---|---|---|---|
| file | multipart file | required | The file you want to upload to Universign. Expected file format is PDF, and size must not exceed 25MB. |
Returns
The API returns a file object containing a file id, as shown in the code example.
Response example
{
"object" : "file",
"id" : "file_d0bDo8LgEkEA",
}
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is file. |
| id | string | The file ID generated by Universign, which will be used to add the document to the transaction. |
Add the file ID to Universign
POST /v1/transactions/{transaction_id}/documents
To add your document to the transaction, you must pass the value of the file id as a request parameter, as follows. You must add one document per request.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents \
-d document=file_Jak61BXwknZv8HVbJEgbJ5zvDO \
-d name=DocName
| Arguments | Type | Description | |
|---|---|---|---|
| document | string | required | The document to be added to the transaction, referenced by its file id. |
| name | string | optional | The name of the document. Default value is the filename value. |
| archiving_configuration_id | string | optional | The ID of the signed documents archiving configuration. To be retrieved from your workspace. For more information about archiving configuration, refer to Archive signed documents. |
Returns
For each request, you are returned a new document sub-object, as shown in the code example.
Response example
{
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : true,
"fields" : [ ],
"big_file" : false,
"available" : true
}
Update a document in a transaction
POST /v1/transactions/{transaction_id}/documents/{document_id}
This endpoint enables you to change the name of a document. You can do so until the document has been signed or reviewed by a participant.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL \
-d name=DocName
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | optional | The name of the document. Default value is the filename value. |
| archiving_configuration_id | string | optional | The ID of the signed documents archiving configuration. To be retrieved from your workspace. For more information about archiving configuration, refer to Archive signed documents. |
| delete_archiving_configuration_id | boolean | optional | Set to true if you want your signed documents to be archived only through our internal archiving system. Do not pass this parameter if you pass the archiving_configuration_id parameter. |
Returns
The response returns a document sub-object, updated with a new name, as shown in the code example.
Response example
{
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : true,
"fields" : [ ],
"big_file" : false,
"available" : true
}
Delete a document from a transaction
DELETE /v1/transactions/{transaction_id}/documents/{document_id}
You can delete a document from a transaction as long as it does not contain any field.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_XqxK \
-X DELETE
Returns
A successful request returns an empty 200 response.
Response example
Revoke document download in a transaction
POST /v1/transactions/{transaction_id}/documents/{document_id}/revoke-download
Once a transaction is cancelled, expired, completed or archived you can revoke documents download. In this case, concerned documents can no longer be downloaded.
You must revoke documents download individually.
Note that when a document download is revoked from a completed transaction, it will also be revoked from its archive, and vice versa.
Request example
curl https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_6Amd/revoke-download \
Returns
A successful request returns an empty 200 response.
Response example
Add a field to a document
POST /v1/transactions/{transaction_id}/documents/{document_id}/fields
This endpoint enables you to create a field in the document and set a series of optional or required parameters (depending on the field type), as listed in the table below.
Request examples
To create a visible signature field in the document:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields \
-d name=customerField \
-d page=1 \
-d x=75 \
-d y=200
To create an invisible signature field in the document:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields \
-d name=myField
To create a visa field:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields \
-d name=agentField \
-d type=visa
To create a text field
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields \
-d type=text \
-d name=TextField \
-d page=1 \
-d x=75 \
-d y=200 \
-d tooltip=Please add your comments here.
To create a label field
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields \
-d type=label \
-d name=LabelField \
-d page=1 \
-d x=75 \
-d y=200 \
-d value=This text cannot be edited! \
-d font_size=10
To create a checkbox group field
curl https://api.universign.com/v1/transactions/tx_d2VGr6ADPYvy/documents/doc_2ZAz/fields \
\
-d type=checkbox_group \
\
-d name=CheckboxGroup1 \
\
-d minimum_required=1
To create a checkbox field
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
To create a radio button group field
curl https://api.universign.com/v1/transactions/tx_d2VGr6ADPYvy/documents/doc_2ZAz/fields \
\
-d type=radio_group \
\
-d name=RadioGroup1 \
To create a radio button field
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
\
-d type=radiobutton \
\
-d parent=RadioGroup1 \
\
-d name=RadioButton1 \
\
-d page=1 \
\
-d x=220 \
\
-d y=154 \
To create a dropdown list field
curl https://api.universign.com/v1/transactions/tx_d2VGr6ADPYvy/documents/doc_2ZAz/fields \
\
-d type=dropdown \
\
-d name=DropdownList1 \
\
-d options[key1]=Option1 \
\
-d options[key2]=Option2 \
\
-d options[key3]=Option3 \
\
-d value=Option1 \
\
-d required=true \
\
-d page=1 \
\
-d x=220 \
\
-d y=154 \
\
-d height=19 \
\
-d width=200 \
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | optional | The name of the field. Note that the field name is required for checkbox_group, checkbox, radio_group, radiobutton and dropdown field types. |
| type | string | optional | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| anchor | string | optional | Allows you to position a signature field on a PDF anchor. Pass the anchor name as the value. If no x and y parameters are passed, the field upper left corner will be positioned on the anchor lower left corner. Set only if field type is signature. |
| page | int | optional | The page number on which you want to position the field. Note that if you passed the anchor parameter and if you pass a page number, the system will look for the anchor value in this page only. Note that the page number is required if field type is dropdown. |
| x | int | optional | The field horizontal coordinate on the document page (in pixels). If you passed the anchor parameter, the system calculates the x coordinate in relation to the found anchor value. Note that the x argument is required if field type is dropdown. |
| y | int | optional | The field vertical coordinate on the document page (in pixels). If you passed the anchor parameter, the system calculates the y coordinate in relation to the found anchor value. Note that the y argument is required if field type is dropdown. |
| consents | array of strings | optional | Mandatory consents to agree to when signing the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Set only if field type is signature or visa. |
| optional_consents | array of strings | optional | Optional consents to agree to when signing the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Set only if field type is signature or visa. The feature needs to be activated on your workspace. |
| copy_from | string | optional | Use to copy the field. Expected value is the ID of the field you want to copy. This creates a new field with no position on the document. Do not pass if you pass the move_from argument. Do not pass if field type is one of checkbox_group, checkbox, radio_group, radiobutton, dropdown. |
| move_from | string | optional | Use to move a field to another document. Expected value is the ID of the field you want to move. Do not pass if you pass the copy_from argument. |
| height | string | optional | The height of the field (expressed in PDF's default user space units). Set only if field type is text, label or dropdown. If not provided, the height is set to font height. Default value is 19. |
| width | string | optional | The width of the field (expressed in PDF's default user space units). Set only if field type is text, label or dropdown. Default value is 200. |
| tooltip | string | optional | Tooltips about the text the participant needs to add to the document during signature process. Set only if field type is text. Max 100 characters. |
| value | string | optional | Set only if field type is label or dropdown. If field type is label, it is the text you want to display in the label field. If field type is dropdown, it is the value of the dropdown option that will be selected by default for the dropdown list. If set, the value cannot be left empty and must not exceed 200 characters. The option value must not contain a backslash \. |
| font_size | number | optional | The font size of the field content. Possible values between 7 and 12. Default value is 12. Set only if field type is label. |
| checked | boolean | optional | Set to true if you want the checkbox field or the radio button to be already checked. Default value is false. Set only if field type is checkbox or radiobutton. For more details, refer to Add checkbox fields or Add radio button fields. |
| minimum_required | int | optional | The minimum number of checkboxes to be checked by the participant. Default value is 0. Displays only if field type is checkbox_group. |
| parent | string | required | The ID or the unique name of the parent checkbox group or radio button group to which the checkbox/radio button is linked. Set only if field type is checkbox or radiobutton. For more details, refer to Add checkbox fields or Add radio button fields. |
| required | boolean | optional | Whether the participant must choose an option or not. Set only if field type is dropdown. Default value is true. |
| options[*] | string | optional | To add a dropdown option, you must specify it as a key-value pair. The value of the options key must be appended to the options field between brackets (for example options[key]), and must not exceed 20 characters. The option key-value pair must be unique within the same dropdown list and the value must not exceed 200 characters. You can add up to 15 options per dropdown list. Note that the options value cannot be left empty and must not contain a backslash \. |
Returns
The API returns a field sub-object.
Response examples
For a signature field visible on the document:
{
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}
For an invisible field:
{
"id" : "fld_VoDl",
"name" : "myField",
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}
For a visa field:
{
"id" : "fld_6MY4",
"name" : "agentField",
"type" : "visa",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}
For a text field
{
"id" : "fld_DL4x",
"name" : "TextField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please add your comments here.",
"required" : true,
"font_size" : 12,
"type" : "text"
}
For a label field
{
"id" : "fld_3znk",
"name" : "LabelField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 180,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This text cannot be edited!",
"font_size" : 10,
"type" : "label"
}
For a checkbox group field
{
"id": "fld_w4Dw",
"name": "CheckboxGroup1",
"type": "checkbox_group",
"minimum_required": 1,
"built_in": false,
"updatable": true,
"deletable": true
}
For a checkbox field
{
"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"
}
For a radio button group field
{
"id" : "fld_3zyB",
"name" : "RadioGroup1",
"type" : "radio_group",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"required" : true
}
For a radio button field
{
"id" : "fld_WWB",
"name" : "RadioButton1",
"type" : "radiobutton",
"position" : {
"page" : 1,
"x" : 220,
"y" : 154,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "RadioGroup1",
"checked" : false
}
For a dropdown list field
{
"id" : "fld_mgz1",
"name" : "dropdownList1",
"type" : "dropdown",
"position" : {
"page" : 1,
"x" : 220,
"y" : 154,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"font_size" : 12,
"options" : {
"key1" : "Option1",
"key2" : "Option2",
"key3" : "Option3"
},
"value" : "Option1",
"required" : true
}
| Parameters | Type | Description |
|---|---|---|
| id | string | The field ID. |
| name | string | The name of the field. |
| type | string | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| built_in | boolean | Whether the field is built-in the PDF. |
| consents | array of strings | Mandatory consents to agree to when signing the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| optional_consents | array of strings | Optional consents to agree to when signing the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| updatable | boolean | Whether the field is currently updatable or not. |
| deletable | boolean | Whether the field is is currently deletable or not. |
| position | object | The position of the field on the document. |
| position.page | int | The page number on which the field is positioned. |
| position.x | int | The field horizontal coordinate on the document page (in pixels). |
| position.y | int | The field vertical coordinate on the document page (in pixels). |
| position.height | string | The height of the field (expressed in PDF's default user space units). Displays only if field type is text, label or dropdown. If not provided, the height is set to font height. Default value is 19. |
| position.width | string | The width of the field (expressed in PDF's default user space units). Displays only if field type is text, label or dropdown. Default value is 200. |
| font_size | number | The font size of the field content. Possible values between 7 and 12. Default value is 12. |
| max_length | number | The max length of the field content. Displays only if field type is text. |
| tooltip | string | Tooltips about the text the participant needs to add to the document during signature process. Displays only if field type is text. |
| value | string | Displays only if field type is label or dropdown. If field type is label, it is the text you want to display in the label field. If field type is dropdown, it is the value of the dropdown option that will be selected by default for the dropdown list. |
| alignment | string | The alignment of initial fields content. Displays only for initials-fields. |
| checked | boolean | Whether the checkbox or radio button field is already checked or not. Displays only if field type is checkbox or radiobutton. |
| minimum_required | int | The minimum number of checkboxes to be checked by the participant. Default value is 0. Displays only if field type is checkbox_group. |
| parent | string | The ID of the parent checkbox group or radio button group. Displays only if field type is checkbox or radiobutton. |
| required | boolean | Whether the participant must choose an option or not. Displays only if field type is dropdown. Default value is true. |
| options[*] | string | The dropdown options key-value pairs. |
Add initials fields to a document
POST /v1/transactions/{transaction_id}/documents/{document_id}/initials-fields
This endpoint enables you to create initials fields in the document and set a series of optional or required parameters, as listed in the table below. You can request initials fields only once per document. Note that initials fields are added to all pages of the document (as shown in the reponse example below).
Request example
curl https://api.universign.com/v1/transactions/tx_qoMGgYXm7AX3/documents/doc_Kzk1/initials-fields
\
-d y=200
\
-d alignment=center
| Arguments | Type | Description | |
|---|---|---|---|
| y | int | required | The field vertical coordinate on the document pages (expressed in the PDF’s default user space units). The origin point is the bottom left hand corner of the displayed page (i.e the PDF's cropbox). |
| alignment | string | optional | The alignment of the initials fields content. Possible values are left, center or right. Default value is right. |
Returns
The API returns a field sub-object with the list of initials fields added to all document pages.
Response examples
[ {
"id" : "fld_kVlx",
"position" : {
"page" : 1,
"x" : 0,
"y" : 200,
"width" : 595,
"height" : 19
},
"type" : "initials",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12,
"alignment" : "center"
}, {
"id" : "fld_xrA",
"position" : {
"page" : 4,
"x" : 0,
"y" : 200,
"width" : 595,
"height" : 19
},
"type" : "initials",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12,
"alignment" : "center"
}, {
"id" : "fld_rDL7",
"position" : {
"page" : 5,
"x" : 0,
"y" : 200,
"width" : 595,
"height" : 19
},
"type" : "initials",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12,
"alignment" : "center"
}, {
"id" : "fld_9lGa",
"position" : {
"page" : 2,
"x" : 0,
"y" : 200,
"width" : 595,
"height" : 19
},
"type" : "initials",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12,
"alignment" : "center"
}, {
"id" : "fld_ZDDX",
"position" : {
"page" : 3,
"x" : 0,
"y" : 200,
"width" : 595,
"height" : 19
},
"type" : "initials",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12,
"alignment" : "center"
} ]
Update a field in a document
POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}
This endpoint enables you to update the parameters of an existing field by passing the following arguments:
Request examples
To make an invisible field visible:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields/fld_VoDl \
-d page=1 \
-d x=325 \
-d y=200
To make a visible field invisible:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields/fld_6MY4 \
-d type=signature \
-d page=0
To turn a signature field into a visa field:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields/fld_6MY4 \
-d type=visa
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | optional | The name of the field. Note that the field name is required for checkbox_group, checkbox, radio_group, radiobutton and dropdown field types. |
| type | string | optional | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| anchor | string | optional | Allows you to position a signature field on a PDF anchor. Pass the anchor name as the value. If no x and y parameters are passed, the field upper left corner will be positioned on the anchor lower left corner. Set only if field type is signature. |
| page | int | optional | The page number on which you want to position the field. Note that if you passed the anchor parameter and if you pass a page number, the system will look for the anchor value in this page only. Note that the page number is required if field type is dropdown. |
| x | int | optional | The field horizontal coordinate on the document page (in pixels). If you passed the anchor parameter, the system calculates the x coordinate in relation to the found anchor value. Note that the x argument is required if field type is dropdown. |
| y | int | optional | The field vertical coordinate on the document page (in pixels). If you passed the anchor parameter, the system calculates the y coordinate in relation to the found anchor value. Note that the y argument is required if field type is dropdown. |
| consents | array of strings | optional | Mandatory consents to agree to when signing the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Set only if field type is signature or visa. |
| optional_consents | array of strings | optional | Optional consents to agree to when signing the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Set only if field type is signature or visa. The feature needs to be activated on your workspace. |
| copy_from | string | optional | Use to copy the field. Expected value is the ID of the field you want to copy. This creates a new field with no position on the document. Do not pass if you pass the move_from argument. Do not pass if field type is one of checkbox_group, checkbox, radio_group, radiobutton, dropdown. |
| move_from | string | optional | Use to move a field to another document. Expected value is the ID of the field you want to move. Do not pass if you pass the copy_from argument. |
| height | int | optional | The height of the field (expressed in PDF's default user space units). Set only if field type is text, label or dropdown. If not provided, the height is set to font height. Default value is 19. |
| width | int | optional | The width of the field (expressed in PDF's default user space units). Set only if field type is text, label or dropdown. Default value is 200. |
| tooltip | string | optional | Tooltips about the text the participant needs to add to the document during signature process. Set only if field type is text. Max 100 characters. |
| value | string | optional | Set only if field type is label or dropdown. If field type is label, it is the text you want to display in the label field. If field type is dropdown, it is the value of the dropdown option that will be selected by default for the dropdown list. If set, the value cannot be left empty and must not exceed 200 characters. The option value must not contain a backslash \. |
| font_size | number | optional | The font size of the field content. Possible values between 7 and 12. Default value is 12. Set only if field type is label. |
| checked | boolean | optional | Set to true if you want the checkbox field or the radio button to be already checked. Default value is false. Set only if field type is checkbox or radiobutton. For more details, refer to Add checkbox fields or Add radio button fields. |
| minimum_required | int | optional | The minimum number of checkboxes to be checked by the participant. Default value is 0. Displays only if field type is checkbox_group. |
| parent | string | required | The ID or the unique name of the parent checkbox group or radio button group to which the checkbox/radio button is linked. Set only if field type is checkbox or radiobutton. For more details, refer to Add checkbox fields or Add radio button fields. |
| required | boolean | optional | Whether the participant must choose an option or not. Set only if field type is dropdown. Default value is true. |
| options[*] | string | optional | To add a dropdown option, you must specify it as a key-value pair. The value of the options key must be appended to the options field between brackets (for example options[key]), and must not exceed 20 characters. The option key-value pair must be unique within the same dropdown list and the value must not exceed 200 characters. You can add up to 15 options per dropdown list. Note that the options value cannot be left empty and must not contain a backslash \. |
Returns
The API returns a field sub-object, updated with the values you entered as request parameters.
Response examples
For an invisible field changed into a visible field:
{
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}
For a visible field changed into an invisible field:
{
"id" : "fld_6MY4",
"name" : "agentField",
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}
For a signature field changed into an visa field:
{
"id" : "fld_6MY4",
"name" : "agentField",
"type" : "visa",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}
Delete a field from a document
DELETE /v1/transactions/{transaction_id}/fields/{field_id}
This endpoint enables you to delete a field from a document. Please note that a field can be deleted only if it has no signer linked to it. If it does, you need to remove the signer before you can delete the field.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/documents/doc_6AVL/fields/fld_6MY4 \
-X DELETE
Returns
A successful request returns an empty 200 response.
Response example
Transaction instructions
Transaction instructions endpoints
POST /v1/transactions/{transaction_id}/signatures
POST /v1/transactions/{transaction_id}/seals/{seal_id}
POST /v1/transactions/{transaction_id}/reviews
POST /v1/transactions/{transaction_id}/editions
POST /v1/transactions/{transaction_id}/sequencing
POST /v1/transactions/{transaction_id}/participants
GET /v1/transactions/{transaction_id}/participants/messages
POST /v1/transactions/{transaction_id}/participants/messages
POST /v1/transactions/{transaction_id}/participants/messages/{message_id}
POST /v1/transactions/{transaction_id}/participants/remind
Manage signatures and visas
POST /v1/transactions/{transaction_id}/signatures
This endpoint enables you to assign a signer to a field. If you wish to assign alternate signers to the same field, your requests must be performed individually (one request per participant). To remove a signer from a field, simply pass a delete parameter in your request.
Request example
To add a participant to a field:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/signatures \
-d signer=jane@universign.com \
-d field=fld_6V4P
| Arguments | type | Description | |
|---|---|---|---|
| signer | string | required | The participant's email address, designation (is case the participant is unknown) or the moral person's certificate ID you want to assign to the field. |
| field | string | required | The field ID or field name that bears the signature or visa task. |
| delete | boolean | optional | Set to true to remove the signer from the field. |
Returns
The API returns a transaction object, updated with a new signature instruction in the instructions sub-object and a new task in the actions array, as shown in the code example.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : true
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"max_expiry" : "180_days",
"private" : false
}
Update a seal
POST /v1/transactions/{transaction_id}/seals/{seal_id}
You may need to use a custom logo for the seal that will display on your document. You can use either the Universign logo, the issuing entity logo or even seal a document with no logo. This endpoint, allows you to define the logo that will display on your sealed document.
Request example
curl https://api.universign.com/v1/transactions/tx_qoMGgYXm7AX3/seals/scd_5x \
\
-d logo_display=issuing_entity
| Arguments | type | Description | |
|---|---|---|---|
| logo_display | string | optional | The sealer logo that will display on the document. Accepted values are certificate (Universign logo), issuing_entity (issuing entity logo), none (no logo to display). |
Returns
The API returns a seal sub-object.
Response example
{
"id": "scd_5x",
"name": "scdName",
"logo_display": "issuing_entity"
}
Manage reviews
POST /v1/transactions/{transaction_id}/reviews
You may need someone to approve documents before they are sent to a participant. This endpoint enables you to appoint a reviewer to approve the documents of a participant. Note that a reviewer systematically reviews all the recipient's documents. To remove a review instruction, simply pass a delete parameter in your request.
Request example
To add a reviewer to a participant:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/reviews \
-d reviewer=carol@universign.com \
-d recipient=jane@universign.com
| Arguments | type | Description | |
|---|---|---|---|
| reviewer | string | required | The reviewer's email address. |
| recipient | string | required | The email address of the participant for whom the review is intended. |
| delete | boolean | optional | Set to true if you want to delete the review instruction on a participant. |
Returns
The API returns a transaction object, updated with a new review instruction in the instructionssub-object and a new task in the actions array, as shown in the code example.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ {
"email" : "carol@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ {
"reviewer" : "carol@universign.com",
"recipient" : "jane@universign.com"
} ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
}, {
"id" : "act_dqlnwEzG50eny",
"actor" : "carol@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_dqlnwEzG50eny",
"tasks" : [ {
"type" : "review",
"state" : "todo",
"recipient" : "jane@universign.com",
"document" : "doc_6AVL"
} ],
"stalled" : false
}, {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"max_expiry" : "180_days",
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Manage editions
POST /v1/transactions/{transaction_id}/editions
You may not know the identity of the signer upon the transaction creation. Therefore, you may add an unknown participant to your transaction and assign him/her an editor. This endpoint enables you to assign an editor that will fill the unknown participant information. To remove an edition instruction, simply pass a delete parameter in your request.
Request example
To assign an editor to a participant:
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/editions \
-d editor=John@universign.com \
-d recipient=$Designation
| Arguments | type | Description | |
|---|---|---|---|
| editor | string | required | The editor's email address or designtation if s/he is unknown. |
| recipient | string | required | The unkown participant designation. |
| delete | boolean | optional | Set to true if you want to delete the edition instruction on a participant. |
Returns
The API returns a transaction object, updated with a new edition instruction in the instructionssub-object and a new task in the actions array, as shown in the code example.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"request_full_name" : false,
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 0
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ {
"editor" : "John@universign.com",
"recipient" : "$Designation"
} ]
},
"actions" : [ {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
}, {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"max_expiry" : "180_days",
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Manage order between participants
POST /v1/transactions/{transaction_id}/sequencing
By default, participants can perform their actions simultaneously when the transaction is started. However, you can set an order of action between participants. To do so, you must specify in your request which signer must perform his/her action before which other signer. Note that sequencing requests must be sent individually, you must therefore send as many requests as sequencing instructions. To remove a sequencing instruction between two participants, simply pass a delete parameter in your request.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/sequencing \
-d before=jane@universign.com \
-d after=jean@universign.com
| Arguments | Type | Description | |
|---|---|---|---|
| before | array of strings | required | The participant (identified by its email) or sealer (identified by its ID) that you want to position before the participant or sealer specified in the after field. |
| after | array of strings | required | The participant (identified by its email) or sealer (identified by its ID) that you want to position after the participant or sealer specified in the before field. |
| delete | boolean | optional | Set to true if you want to delete a sequential order between the two participants. |
Returns
A successful sequencing request returns a transaction object updated with the sequencing instruction you passed in your request.
If the sequencing request is not coherent, you are returned an error message reading "Cycle!" as an error_description.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"request_full_name" : false,
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 0
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ {
"before" : "jane@universign.com",
"after" : "jean@universign.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
} ],
"stalled" : false
}, {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"max_expiry" : "180_days",
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Manage participants
POST /v1/transactions/{transaction_id}/participants
A participant is an object that is automatically created by the system for each new signer or reviewer you add to the transaction. Note that a transaction can hold a maximum number of 50 participants. You can add more details about a participant by passing the following arguments in your request.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/participants \
-d email=jane@universign.com \
-d invitation_message=SampleMessage \
-d waiting_period=7
| Arguments | Type | Description | |
|---|---|---|---|
| string | required | The participant's address email. | |
| designation | string | required | The unknown participant designation. Max 250 characters. |
| description | string | optional | The unknown participant description. Max 250 characters. |
| invitation_subject | string | optional | The subject of the email invitation. |
| invitation_message | string | optional | The custom invitation message displayed in the email body. We support text format or xml with authorized xhtml tags only. For more details, refer to add invitation message. |
| reminder_subject | string | optional | The subject of the email reminder. |
| reminder_message | string | optional | The custom reminder message displayed in the email body. We support text format or xml with authorized xhtml tags only. For more details, refer to set automatic reminders. |
| signed_documents_subject | string | optional | The subject of the email sent to the participant when signed documents are available. Max 100 characters. |
| signed_documents_message | string | optional | The message sent to the participant when signed documents are available. Max 1000 characters. We support text format or xml with authorized xhtml tags only. |
| prevalidation_id | string | optional | A pre-validated identity to use when issuing a certificate for the participant (for level2 signatures). See Request an identity prevalidation for more details. |
| name_constraint | string | optional | The full name of the participant as it must display in the signature. By passing this parameter, you do not authorize the participant to modify his/her full name, or to sign with a certificate if the full name in the certificate does not match the value you set. Do not pass this parameter if you pass the fullname_suggestion. (Deprecated) See full_name and full_name_type. |
| fullname_prerequisite | string | optional | The full name of the participant as it must display in the signature. By passing this parameter, you do not authorize the participant to modify his/her full name, or to sign with a certificate if the full name in the certificate does not match the value you set. Do not pass this parameter if you pass the fullname_suggestion. (Deprecated) See full_name and full_name_type. |
| fullname_suggestion | string | optional | The participant full name that you suggest for the transaction. If you pass this parameter, the participant will be able to edit his/her name on the signature or review page. Do not pass this parameter if you pass the fullname_prerequisite. (Deprecated) See full_name and full_name_type. |
| full_name | string | optional | The participant full name as it will display in the signature. |
| full_name_type | string | optional | The participant's full name type. Accepted values are suggestion (if you allow the participant to edit his/her name of the signature or review page) or prerequisite (if you don't allow the participant to edit his/her name on the signature or review page). Default value is suggestion. |
| request_full_name | boolean | optional | Set to true if you want the editor to fill the unknown participant full name. |
| phone_number_flex_constraint | string | optional | The participant mobile number that must be used for authentication. If you pass this parameter, the participant will not be able to modify the value you set, only if the minimum signature level requested is level1. However, if you requested a signature with a certificate, and if the participant already owns a certificate linked to a different mobile number, you authorize the participant to authenticate with the mobile number linked to his/her certificate. Do not pass this parameter if you pass the phone_number_suggestion. (Deprecated) See phone_number and phone_number_type. |
| phone_number_flex_prerequisite | string | optional | The participant mobile number that must be used for authentication. If you pass this parameter, the participant will not be able to modify the value you set, only if the minimum signature level requested is level1. However, if you requested a signature with a certificate, and if the participant already owns a certificate linked to a different mobile number, you authorize the participant to authenticate with the mobile number linked to his/her certificate. Do not pass this parameter if you pass the phone_number_suggestion. (Deprecated) See phone_number and phone_number_type. |
| phone_number_suggestion | string | optional | The participant mobile number that you suggest for authentication. If you pass this parameter, the participant will be able to modify the value you set. If the participant owns a certificate linked to a different mobile number, you authorize the participant to authenticate with the mobile number linked to his/her certificate. Do not pass this parameter if you pass the phone_number_flex_prerequisite. (Deprecated) See phone_number and phone_number_type. |
| phone_number | string | optional | The participant mobile number that is used for authentication. Expected format is E.164 ([+][country code][phone number including area code]). |
| phone_number_type | string | optional | The participant's mobile number type. Accepted values are suggestion (if you allow the participant to edit his/her phone number), flex_prerequisite (if you allow the participant to edit his/her phone number for advanced signature only), or prerequisite (if you never allow the participant to edit his/her phone number). Default value is suggestion. |
| request_phone_number | boolean | optional | Set to true if you want the editor to fill the unknown participant phone number. |
| schedule | array of int | optional | The emailing program of the participant. First value indicates how many hours after the participant action is open the system must send the invitation email. Next values indicate how many hours after the invitation email the system must send the reminder emails. Example [0, 48, 72] means that the invitation email must be sent 0 hours after the participant action is open, and that a reminder must be sent 48 hours and 72 hours after the initial invitation. Note that there must be a minimum of 24 hours between each sending. When the transaction is created via the web application, default value is [0]. When the transaction is created by API, default value is [ ] and no invitation is sent. |
| do_not_invite_before | date | optional | The date and time after which the invitation is sent to the participant (after his action is opened). Set this parameter if you want to send a deferred invitation to your participant. Expected input format is ISO 8601 (ex: 2024-03-30T23:00:00Z). |
| stall_trigger | string | optional | Expressed in hours after the participant action is open, this value specifies the allotted time for the participant to perform the action. Beyond this delay, the participant will be flagged as stalled. |
| delete_stall_trigger | boolean | optional | Set to true if you want to delete the stall_trigger on a participant. |
| min_signature_level | string | optional | The minimum required level of signature for a participant. Possible values are level0 (simple signature without authentication), level1 (simple signature), level2 (advanced signature), level3(advanced signature with qualified certificate) and level4 (qualified signature). Default value is level1. Note that the level0, level2, level3 and level4 signatures depend on your workspace entitlements. |
| waiting_period | number | optional | The reflection period the participant has to respect before s/he can sign his/her documents. Currently, we only support this parameter with level1 signatures. |
Returns
Response example
{
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"invitation_message" : "SampleMessage",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 7,
"full_name_type" : "suggestion"
}
Retrieve a conversation
GET /v1/transactions/{transaction_id}/participants/messages
If a participant has sent a message to the transaction creator via the signature page instant messaging feature, it is possible to retrieve the content of this conversation.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/participants/messages?email=jane@universign.com \
-X GET
| Arguments | Type | Description | |
|---|---|---|---|
| string | required | The participant's address email for whom you want to retrieve the conversation. |
Returns
The API returns the existing messages between the participant and the workspace member who replied to the participant, as in the description below:
Response example
[ {
"object" : "message",
"id" : "msg_mGZ8Qm9XYVZJW",
"sent_at" : "2024-10-08T08:22:53Z",
"message" : "Done",
"from_participant" : false,
"was_read" : false
} ]
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is message. |
| id | string | The the message ID. |
| sent_at | date | The date the message was sent. Returned format is ISO 8601. |
| message | string | The message itself. |
| message_type | string | The message type. Displays only if the message was sent when the participant refused the documents. Value is signature_refusal if the message was sent when the participant refused a document to sign, review_refusal if he refused a document to review, consultation_refusal if he refused a document to read, or transaction_refusal if the participant refused at a later stage. |
| from_participant | boolean | true if the message comes from the participant. false if the message was written by a workspace member. |
| was_read | boolean | true if the message was read by its recipient. |
Reply to a participant message
Replying to a participant message is a two-step process that consists of:
- sending a message to the participant.
- marking the participant message as read.
Send a message to the participant
POST /v1/transactions/{transaction_id}/participants/messages
If a participant has sent a message via the chat box on the signature page, it is possible to reply via API.
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/participants/messages \
-d email=jane@universign.com \
-d message=Done
| Arguments | Type | Description | |
|---|---|---|---|
| string | required | The participant's email address. | |
| message | string | required | The message sent to the participant. |
Returns
The API returns a message object.
Response example
{
"object" : "message",
"id" : "msg_mGZ8Qm9XYVZJW",
"sent_at" : "2024-10-08T08:22:53Z",
"message" : "Done",
"from_participant" : false,
"was_read" : false
}
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is message. |
| id | string | The message ID. |
| sent_at | date | The date the message was sent. Returned format is ISO 8601. |
| message | string | The message itself. |
| from_participant | boolean | false as the message was not sent by the participant. |
| was_read | boolean | true if the message was read by the participant. |
Mark a participant message as read
POST /v1/transactions/{transaction_id}/participants/messages/{message_id}
To mark a participant message as read, pass the participant email as a request parameter, as follows.
Request example
curl https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/participants/messages/msg_1aZMnyLZB477e \
\
-d email=john@company.com
| Arguments | Type | Description | |
|---|---|---|---|
| string | required | The participant's email address. |
Returns
The API returns a message object.
Response example
{
"object": "message",
"id": "msg_1aZMnyLZB477e",
"sent_at": "2022-01-19T18:45:44Z",
"message": "Thank you for your reply.",
"from_participant": true,
"was_read": true
}
Send manual reminders
POST /v1/transactions/{transaction_id}/participants/remind
This endpoint enables you to send manual reminders to participants of the transaction that have not yet completed their actions. If you want the participants to receive the reminder email, you need to set the schedule parameter first (refer to Manage participants).
Request example
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/participants/remind \
-d email=jane@universign.com
| Arguments | Type | Description | |
|---|---|---|---|
| string | optional | The participant's email address. If not set, all participants with an action open will receive a manual reminder. |
Returns
The API returns a transaction object.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"request_full_name" : false,
"full_name_type" : "suggestion"
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"invitation_message" : "SampleMessage",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 7,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ {
"before" : "jane@universign.com",
"after" : "jean@universign.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
} ],
"stalled" : false
}, {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"max_expiry" : "180_days",
"private" : false
}
Transaction archives
Archives endpoints
GET /v1/archives
GET /v1/archives/{transaction_id}
GET /v1/archives/{transaction_id}/requester-attestation
POST /v1/archives/{transaction_id}/documents/{document_id}/revoke_download
Once a transaction is completed, it is archived. This operation may take a few seconds or minutes depending on the number of documents and participants. Calls to the /archives endpoint enable you to retrieved information about an archived transaction and to retrieve signed documents.
The Transaction archive object
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is transaction_archive. |
| id | string | The ID of the transaction. |
| created_at | date | The date the transaction was created. Format ISO 8601. |
| started_at | date | The date the transaction was started. Format ISO 8601. |
| closed_at | date | The date the transaction was closed. Format ISO 8601. |
| name | string | The name of the transaction. |
| language | string | The language of the transaction. |
| folder_id | string | The ID of the folder associated with the archived transaction. |
| folder_name | string | The name of the folder associated with the archived transaction. |
| creator.email | string | The archived transaction creator email. |
| creator.name | string | The archived transaction creator name. |
| creator.api_key_id | string | The creator API key ID that was used to authenticate the API request. |
| participants | string | The list of participants of the transaction. |
| participants[ ].email | string | The participant email. |
| participants[ ].name | string | The participant name. |
| documents | string | The list of documents. |
| documents[ ].id | string | The document ID |
| documents[ ].name | string | The document name. |
| metadata | object | The list of metadata associated with the transaction. |
| metadata.* | string | The metadata entries, represented as key-value pairs. |
| issuing_entity | object | Information about the issuing entity of the transaction. |
| issuing_entity.id | string | The ID of the issuing entity. |
| issuing_entity.name | string | The name of the issuing entity. |
List all archived transactions
GET /v1/archives
This endpoint enables you to retrieve all the archived transactions that you have the permission to view and pass a series of optional filters to refine your request.
Request example
curl https://api.universign.com/v1/archives?size=1
| Arguments | Type | Description | |
|---|---|---|---|
| size | int | optional | The number of archived transactions you want to retrieve, starting from the most recent. Maximum is 100, default is 50. |
| starting_after | string | optional | Expected value is a transaction ID. Use for pagination to return the archived transactions listed after the specified archived transaction. |
| folder_id | string | optional | Returns only archived transactions associated with this folder ID. |
| creator | string | optional | Expected value is an email address. Returns only archived transactions created by the workspace member associated with this email. |
| created_gt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns only archived transactions created at and after the specified date. |
| created_lt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns only archived transactions created at and before the specified date. |
| closed_at_gt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns only archived transactions closed after the specified date. Must be lower than closed_at. |
| created_at_lt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns only archived transactions closed before the specified date. Must be greater than closed_at. |
| text_search | string | optional | Returns archived transactions that contain the specified string in one of : transaction name, transaction ID, participant name, participant email, document name, seal ID, seal name and metadata values. To search for a string that starts with a specific string, append ^ to the value (example: ^john will retrieve all occurences starting with john. |
| private | boolean | optional | Returns only private archived transactions. |
| issuing_entity_id | string | optional | Returns only archived transactions created by a given issuing entity. |
| creator_api_key_id | string | optional | Expected value is an API key ID. Returns only archived transactions created by the API key that authenticated the transaction API request. |
Returns
The API returns the list of all archived transactions matching your request. The response description is as follows:
Response example
{
"has_more" : true,
"content" : [ {
"object" : "transaction-archive",
"id" : "tx_qGzGg79gaZaJ",
"created_at" : "2022-09-13T09:45:38Z",
"started_at" : "2022-09-13T09:50:46Z",
"closed_at" : "2022-09-13T09:51:42Z",
"name" : "Archived_transaction_name",
"language" : "fr",
"folder_id" : "fol_JqqOX1OY778L",
"folder_name" : "Default folder",
"creator" : {
"email" : "john.doe@company.com",
"name" : "John Doe"
},
"participants" : [ {
"email" : "jane.doe@company.com",
"name" : "Jane Doe"
} ],
"documents" : [ {
"id" : "doc_eVY2",
"name" : "A signer.pdf"
} ],
"metadata" : { },
"uploads" : [ ],
"private" : false
}
| Parameters | Type | Description |
|---|---|---|
| has more | boolean | If there are more existing archived transactions in the workspace than the archived transactions returned in the response. |
| content | string | The list of archived transactions. |
| content[ ].object | string | The object's type. Value is transaction-archive. |
| content[ ].id | string | The transaction ID. |
| content[ ].created_at | date | The archived transaction creation date. Returned format is ISO 8601. |
| content[ ].started_at | date | The archived transaction start date. Returned format is ISO 8601. |
| content[ ].closed_at | date | The archived transaction closing date. Returned format is ISO 8601. |
| content[ ].name | string | The archived transaction name. |
| content[ ].language | string | The archived transaction language. Returned format is ISO 639-1. |
| content[ ].folder_id | string | The ID of the folder associated with the archived transaction. |
| content[ ].folder_name | string | The name of the folder associated with the archived transaction. |
| content[ ].creator | object | Information regarding the creator of the archived transaction. |
| content[ ].creator.name | string | The full name of the person who created the archived transaction, if the transaction was created via the web application. |
| content[ ].creator.email | string | The email of the person who created the archived transaction, if the transaction was created via the web application. |
| content[ ].creator.api_key_id | string | The ID of the API key that authenticated the archived transaction API request. |
| content[ ].participants | array | The list of participants. |
| content[ ].participants[ ].email | string | The participant email. |
| content[ ].participants[ ].name | string | The participant name. |
| content[ ].documents | array | The list of signed documents. |
| content[ ].documents[ ].id | string | The id of the signed document. |
| content[ ].documents[ ].name | string | The name of the signed document. |
| content[ ].uploads | array | If you requested a capture, the list of documents uploaded by the participant. |
| content[ ].uploads[ ].actor | string | The actor of the captured document. |
| content[ ].uploads[ ].captured_documents | array | Information about the captured documents. |
| content[ ].uploads[ ].captured_documents[ ].id | string | The captured document id. |
| content[ ].uploads[ ].captured_documents[ ].document_type | string | The type of the captured document. |
| content[ ].uploads[ ].captured_documents[ ].captured_at | string | The capture date. |
| content[ ].uploads[ ].captured_documents[ ].name | string | The name of the captured document. |
| content[ ].uploads[ ].captured_documents[ ].tag | string | The tag of the captured document. |
| content[ ].uploads[ ].captured_documents[ ].tax_year | number | The captured document's tax year(s). |
| content[ ].uploads[ ].captured_documents[ ].accepted_identity_documents | array | The capture’s accepted identity documents. |
| content[ ].metadata | object | The list of metadata. The key-value pairs of this object represent the key-value pairs of the archived transaction's metadata. |
| content[ ].metadata.* | string | The metadata entries you associated with the archived transaction. |
| content[ ].private | boolean | Whether the archived transaction is private or not. |
Retrieve an archived transaction
GET /v1/archives/{transaction_id}
Archived transactions can be retrieved via the /archives endpoint. Note that archived transactions are also available via the /transactions endpoint for 60 days. After this period, an archived transaction can only be retrieved via the /archives endpoint.
Request example
curl https://api.universign.com/v1/archives/tx_YxwdbnAdl9vO \
Returns
The API returns a transaction_archive object.
Response example
{
"object": "transaction-archive",
"transaction_id": "tx_YxwdbnAdl9vO",
"created_at": "2021-09-13T13:12:07Z",
"started_at": "2021-09-13T14:13:08Z",
"completed_at": "2021-09-15T17:18:02Z",
"name": "Insurance contract",
"language": "fr",
"participants": [
{
"email": "bob@universign.com"
},
{
"email": "carol@universign.com",
"name": "Carol Smith"
}
],
"documents": [
{
"id": "doc_87oO",
"name": "contract.pdf"
}
],
"metadata": { },
"carbon_copies" : [ ],
"uploads" : [ ],
"private" : false
}
Retrieve the requester attestation
GET /v1/archives/{transaction_id}/requester-attestation
Once a transaction is archived, you can download the requester attestation by passing the transaction ID in the path parameters as in the request example.
Request example
curl https://api.universign.com/v1/archives/tx_wnqKgxAnVgmy/requester-attestation?=lang=fr
| Arguments | Type | Description | |
|---|---|---|---|
| lang | string | optional | The language of the requester attestation. Expected input format is ISO 639-1. We currently support 11 languages: Bulgarian (bg), Catalan (ca), Dutch (nl), English (en), French (fr), German (de), Italian (it), Polish (pl), Portuguese (pt), Romanian (ro) and Spanish (es). Default value is the language of the transaction. |
Returns
The API returns the PDF requester attestation.
Revoke document download in an archived transaction
POST /v1/archives/{transaction_id}/documents/{document_id}/revoke_download
Once a transaction is completed and archived you can revoke documents download. In this case, concerned documents can no longer be downloaded.
You must revoke documents download individually.
Note that when a document download is revoked from an archive, it will also be revoked from the completed transaction, and vice versa.
Request example
curl https://api.universign.com/v1/archives/tx_DwYGle91EQZA/documents/doc_6Amd/revoke_download\
Returns
A successful request returns an empty 200 response.
Response example
Templates
Templates endpoints
GET /v1/templates/{template_id}
GET /v1/templates/
POST /v1/transactions/template
Transaction templates allow you to create transactions from a template that is preconfigured in advance.
The Template object
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is template. |
| id | string | The template ID. |
| template_name | string | The name of the template. |
| folder_id | string | The ID of the folder associated with the template. |
| folder_name | string | The name of the folder associated with the template. |
| created_at | string | The date the template was created as a draft. Returned format is ISO 8601. |
| state | string | The template state. One of draft (unpublished and not yet ready to be used for transaction creation) or published (ready to be used for transaction creation). |
| publishable | boolean | Whether the template is publishable or not. |
| issuing_entity | object | Information about the issuing entity of the template. |
| issuing_entity[ ].name | string | The issuing entity name. |
| issuing_entity[ ].id | string | The ID of the issuing entity. |
| issuing_entity[ ].active | boolean | Whether the issuing entity is active or not. |
| duration | number | The duration of the transaction created from the template. |
| language | string | The language of the future transaction. |
| sender_name_display | string | In whose name the transaction created from the template is sent. If the issuing entity feature is activated, possible values are issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). If the issuing entity feature is deactivated, possible values are workspace (the name of the workspace), name_workspace (the name of the person and the name of the workspace), name_email_workspace (the name and email of the person as well as the name of the workspace). Default value is name_email. |
| metadata | object | The metadata object. The key-value pairs of this object represent the key-value pairs of the template's metadata. |
| metadata.* | string | The metadata entries you associated with the template. Value can be left empty and populated upon transaction creation. |
| carbon_copies | array | The emails you want to notify and give access to signed documents when the transaction created from the template is completed. |
| allow_carbon_copies | boolean | Whether the user of the template can add carbon copies or not. |
| creator | object | Information about the creator of the template. |
| creator[ ].name | string | The name of the workspace member who created the template from the web application. |
| creator[ ].email | string | The email of the workspace member who created the template from the web application. |
| creator[ ].workspace_name | string | The name of the workspace which created the template. |
| instructions | object | The signature and review instructions for the template. Used to link a signer to a field and a reviewer to a participant. Instructions are automatically updated when a signer or a reviewer is added to the template. |
| instructions[ ].signatures | array | Instructions linked to signatures and visas. |
| instructions[ ].signatures.signer | string | The signer's email address or designtation (in case the participant is unknown). |
| instructions[ ].signatures.field | string | The field that bears the signature or visa instruction, designated by its ID. |
| instructions[ ].reviews | array | Instructions linked to reviews. |
| instructions[ ].reviews.reviewer | string | The reviewer's email address. |
| instructions[ ].reviews.recipient | string | The email address of the participant for whom the review is intended. |
| instructions[ ].editions | array | Instructions linked to editions. |
| instructions[ ].editions.editor | string | The editor's email address or designation (in case s/he is unknown). |
| instructions[ ].editions.recipient | string | The reference of the unknown participant to be edited. |
| instructions[ ].captures | array | Instructions linked to captures. |
| instructions[ ].sequencing | array | Sequencing instructions between participants. |
| instructions.sequencing[ ].before | string | The participant (identified by his/her email) who must perform his/her action before the after participant. |
| instructions.sequencing[ ].after | string | The participant (identified by his/her email) who must perform his/her action after the before participant. |
| actions | array | The list of actions to perform. The actions array is automatically updated when a signer or a reviewer is added to the template. |
| actions[ ].id | string | The action ID. |
| actions[ ].actor | string | The email address of the participant having to perform the action. |
| actions[ ].url | url | The URL to the participant's action page. |
| actions[ ].state | string | The state of the action, amongst open (the participant can perform his/her action), waiting (the participant cannot perform his/her action yet) or closed (the action is completed). Please note that an action can be reopened after it was closed: this happens if the transaction created is updated dynamically with new instructions for the actor. |
| actions[ ].stalled | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| actions[ ].stalled_at | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| actions[ ].stalled_reason | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| actions[ ].tasks | array | The tasks list the participant must complete before the action is closed. |
| actions[ ].tasks.field | string | The field ID, if the action type is signature. |
| actions[ ].tasks.document | string | The document associated with the current review task. |
| actions[ ].tasks.recipient | string | The recipient of the review, if the action type is review. |
| actions[ ].tasks.type | string | The task type. Value is signature for a signature or visa task, or review for a review task. |
| actions[ ].tasks.state | string | The state of the task. Can be todo (the participant can perform the requested task), skipped (the task no longer needs to be performed) or done (the participant has performed the requested task). |
| last_publisher | object | Information about the last publisher of the template. |
| last_publisher[ ].name | string | The name of the last publisher of the template. |
| last_publisher[ ].email | string | The email of the last publisher of the template. |
| last_publisher[ ].workspace_name | string | The workspace name of the last publisher of the template. |
| last_publication_date | string | The date the template was last published. |
| participants | array | The list of participants within the transaction. This array is automatically updated when a signer or a reviewer is added to the transaction. |
| participants[ ].email | string | The email address of the participant. |
| participants[ ].designation | string | The designation of the unknown participant. Max 250 characters. |
| participants[ ].description | string | The description of the unknown participant. Max 250 characters. |
| participants[ ].invitation_subject | string | The subject of the participant's invitation email. Max 100 characters. |
| participants[ ].invitation_message | string | The participant's invitation message. Max 1000 characters. |
| participants[ ].reminder_subject | string | The subject of the participant's reminder email. Max 100 characters. |
| participants[ ].reminder_message | string | The participant's reminder message. Max 1000 characters. |
| participants[ ].signed_documents_subject | string | The subject of the email sent to the participant when signed documents are available. Max 100 characters. |
| participants[ ].signed_documents_message | string | The message sent to the participant when signed documents are available. Max 1000 characters. |
| participants[ ].name_constraint | string | The participant full name that must be used in the transaction. (Deprecated) See full_name and full_name_type. |
| participants[ ].fullname_prerequisite | string | The participant full name that must be used in the transaction. (Deprecated) See full_name and full_name_type. |
| participants[ ].fullname_suggestion | string | The participant full name suggestion that can be used in the transaction. (Deprecated) See full_name and full_name_type. |
| participants[ ].full_name | string | The participant full name as it will display in the signature. |
| participants[ ].full_name_type | string | The participant's full name type. One of suggestion or prerequisite. |
| participants[ ].request_full_name | boolean | Value is true if the full name of the unknown participant is requested. |
| participants[ ].phone_number_flex_constraint | string | The participant mobile number that must be used for authentication when the minimum requested signature level is level1. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number_flex_prerequisite | string | The participant mobile number that must be used for authentication when the minimum requested signature level is level1. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number_suggestion | string | The participant mobile number that is suggested for authentication, but can be modified by the participant (or by Universign if the participant owns a certificate linked to a different mobile number.). (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number | string | The participant mobile number that is used for authentication. Expected format is E.164 ([+][country code][phone number including area code]). |
| participants[ ].phone_number_type | string | The participant's mobile number type. One of suggestion, flex_prerequisite or prerequisite. |
| participants[ ].request_phone_number | boolean | Value is true if the phone number of the unknown participant is requested. |
| participants[ ].stall_trigger | int | The allotted time, expressed in hours, for the participant to complete his/her action, from the moment his/her action is open. If the participant is still inactive after that period, the participant action is flagged as stalled and so is the transaction. |
| participants[ ].ongoing_conversation | boolean | Whether there is an ongoing conversation between the participant and the transaction creator. |
| content[ ].participants[ ].has_unread_message | boolean | Whether there is at least one unread message in the conversation. Can be true only if ongoing_conversation is true. |
| participants[ ].schedule | array of int | The emailing schedule of the participant, expressed in hours. |
| participants[ ].do_not_invite_before | date | The date and time after which the invitation is sent to the participant. |
| participants[ ].min_signature_level | string | The minimum required level of signature for a participant among: level0 (simple signature without authentication), level1 (simple signature), level2 (advanced signature), level3(advanced signature with qualified certificate) and level4 (qualified signature). |
| participants[ ].waiting_period | number | The duration in days of the reflection period before the participant can sign his/her documents. |
| participants[ ].shared_contact | boolean | Whether the participant is a shared contact or not. |
| participants[ ].signature_image_reference | string | The reference of the custom signature image displayed on the signature cartridge. |
| sealers | array | The list of seals. |
| sealers[ ].id | string | The moral person's certificate ID. |
| sealers[ ].name | string | The seal common name. |
| documents | array | The documents added to the template. |
| documents[ ].id | string | The document ID. |
| documents[ ].name | string | The name of the document, if you set any. If not, the file name is used. |
| documents[ ].editable | boolean | Whether the document is currently updatable or not. |
| documents[ ].updatable | boolean | Whether the document is currently updatable or not. |
| documents[ ].deletable | boolean | Whether the document is currently deletable or not. |
| documents[ ].fields | array | The list of all fields associated with the document. |
| documents[ ].fields[ ].id | string | The field ID. |
| documents[ ].fields[ ].name | string | The name of the field. |
| documents[ ].fields[ ].type | string | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| documents[ ].fields[ ].built_in | boolean | Whether the field is built-in the PDF. |
| documents[ ].fields[ ].consents | array of strings | Mandatory consents to agree to when signing or reading the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| documents[ ].fields[ ].optional_consents | array of strings | Optional consents to agree to when signing or reading the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| documents[ ].fields[ ].updatable | boolean | Whether the field is currently updatable or not. |
| documents[ ].fields[ ].deletable | boolean | Whether the field is is currently deletable or not. |
| documents[ ].fields[ ].position | object | The position of the field on the document. |
| documents[ ].fields[ ].position.page | int | The page number on which the field is positioned. |
| documents[ ].fields[ ].position.x | int | The field horizontal coordinate on the document page (in pixels). |
| documents[ ].fields[ ].position.y | int | The field vertical coordinate on the document page (in pixels). |
| documents[ ].fields[ ].position.width | int | The field width (in pixels). Default value is 200. |
| documents[ ].fields[ ].position.height | int | The field height (in pixels). Default value is 19 . |
| field_groups | array | The list of field groups in the template. |
| field_groups[ ].id | string | The signable group ID. |
| field_groups[ ].type | string | The signable group type. Possible values are field if there is only one field in the signable group or group if there are more than one. |
| field_groups[ ].fields | object | The list of fields in the signable group. Displays only if the signable group type is group. |
| action_graph | array | The list of actions as a graph. Defines the order between the actions to be performed by participants. |
| action_graph[ ].start | array | List of the first actions to be performed in the template. |
| action_graph[ ].* | array | List of the actions already performed in the template. |
Retrieve a template
GET /v1/templates/{template_id}
This endpoint enables you to retrieve information about a specific template created by your workspace.
Request example
curl https://api.universign.com/v1/templates/tpl_ky4Mygq1de3J
Returns
The request returns a template object, as it was last updated.
Response example
{
"object" : "template",
"id" : "tpl_ky4Mygq1de3J",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-07-09T14:15:18Z",
"duration" : 20160,
"template_name" : "New template",
"folder_name" : "Default folder",
"language" : "fr",
"sender_name_display" : "issuing_entity",
"creator" : {
"name" : "John DOE",
"email" : "koussai.houssine@universign.com",
"workspace_name" : "DemoWS"
},
"state" : "published",
"publishable" : true,
"participants" : [ {
"email" : "$1720534563486",
"designation" : "Employee",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"waiting_period" : 0,
"shared_contact" : false,
"request_full_name" : false,
"full_name_type" : "suggestion"
}, {
"email" : "koussai.houssine@universign.com",
"phone_number" : "+33612345658",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"waiting_period" : 0,
"shared_contact" : false,
"fullname_suggestion" : "Koussai HOUSSINE",
"phone_number_suggestion" : "+33612345658",
"full_name" : "Koussai HOUSSINE",
"full_name_type" : "suggestion"
} ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_QPoP",
"name" : "Contract template.pdf",
"name_locked" : true,
"type" : "final",
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_BJMl",
"type" : "label",
"position" : {
"page" : 2,
"x" : 184,
"y" : 238,
"width" : 0,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12
}, {
"id" : "fld_dQE7",
"position" : {
"page" : 2,
"x" : 315,
"y" : 413,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_wao",
"name" : "chkGroup1727258957748",
"type" : "checkbox_group",
"built_in" : false,
"updatable" : true,
"deletable" : false,
"minimum_required" : 0
}, {
"id" : "fld_E4wb",
"name" : "rbtGroup1727258985188",
"type" : "radio_group",
"built_in" : false,
"updatable" : true,
"deletable" : false,
"required" : true
}, {
"id" : "fld_Yn0O",
"name" : "chkField1727258957853",
"type" : "checkbox",
"position" : {
"page" : 2,
"x" : 66,
"y" : 358,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_wao",
"checked" : false
}, {
"id" : "fld_dxb",
"name" : "chkField1727258974301",
"type" : "checkbox",
"position" : {
"page" : 2,
"x" : 66,
"y" : 338,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_wao",
"checked" : false
}, {
"id" : "fld_97z0",
"name" : "rbtField1727258985291",
"type" : "radiobutton",
"position" : {
"page" : 2,
"x" : 75,
"y" : 144,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_E4wb",
"checked" : false
}, {
"id" : "fld_W0q",
"name" : "rbtField1727258985376",
"type" : "radiobutton",
"position" : {
"page" : 2,
"x" : 75,
"y" : 164,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_E4wb",
"checked" : false
} ],
"available" : true,
"big_file" : false,
"editable" : true
} ],
"field_groups" : [ {
"id" : "fld_dQE7",
"type" : "field",
"fields" : [ "fld_dQE7" ]
}, {
"id" : "fld_wao",
"type" : "field",
"fields" : [ "fld_wao" ]
}, {
"id" : "fld_E4wb",
"type" : "field",
"fields" : [ "fld_E4wb" ]
} ],
"instructions" : {
"signatures" : [ {
"signer" : "$1720534563486",
"field" : "fld_dQE7"
}, {
"signer" : "koussai.houssine@universign.com",
"field" : "fld_wao"
}, {
"signer" : "koussai.houssine@universign.com",
"field" : "fld_E4wb"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_Gx63A6zE67PoP",
"actor" : "koussai.houssine@universign.com",
"tasks" : [ {
"type" : "signature",
"field" : "fld_wao"
}, {
"type" : "signature",
"field" : "fld_E4wb"
} ]
}, {
"id" : "act_3DrknnqXlkKO3",
"actor" : "$1720534563486",
"tasks" : [ {
"type" : "signature",
"field" : "fld_dQE7"
} ]
} ],
"action_graph" : {
"act_Gx63A6zE67PoP" : [ "end" ],
"start" : [ "act_Gx63A6zE67PoP", "act_3DrknnqXlkKO3" ],
"act_3DrknnqXlkKO3" : [ "end" ]
},
"metadata" : { },
"carbon_copies" : [ ],
"allow_carbon_copy" : false,
"last_publication_date" : "2024-09-25T10:10:11Z",
"last_publisher" : {
"name" : "John DOE",
"email" : "koussai.houssine@universign.com",
"workspace_name" : "DemoWS"
},
"issuing_entity" : {
"active" : true,
"name" : "DemoWS",
"id" : "iss_xa1LoEebXQM3"
}
}
List templates
GET /v1/templates
This endpoint enables you to retrieve all the templates created by your workspace that you have the permission to edit and/or view and pass a series of optional filters to refine you request.
Request example
curl https://api.universign.com/v1/templates?size=2
| Arguments | Type | Description | |
|---|---|---|---|
| size | int | optional | The number of templates you want to retrieve, starting from the most recent. Default is 50. |
| ending_before | string | optional | Expected value is a template ID. Use for pagination to return the templates listed before the specified template. Do not pass if you set the starting_after parameter. |
| starting_after | string | optional | Expected value is a template ID. Use for pagination to return the templates listed after the specified template. Do not pass if you set the ending_before parameter. |
| folder_id | string | optional | Returns only templates associated with this folder ID. |
| creator | string | optional | Expected value is an email address. Returns only templates created by the workspace member associated with this email. |
| state | string | optional | Returns only templates with the requested state. Possible values draft or published. |
| issuing_entity_id | string | optional | Returns only templates created by a given issuing entity. |
Returns
The API returns the list of all templates matching your request. The response description is as follows:
Response example
{
"has_more" : false,
"content" : [ {
"object" : "template",
"id" : "tpl_ky4Mygq1de3J",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-07-09T14:15:18Z",
"duration" : 20160,
"template_name" : "New template",
"folder_name" : "Default folder",
"language" : "fr",
"sender_name_display" : "issuing_entity",
"creator" : {
"name" : "John DOE",
"email" : "koussai.houssine@universign.com",
"workspace_name" : "DemoWS"
},
"state" : "published",
"publishable" : true,
"participants" : [ {
"email" : "$1720534563486",
"designation" : "Employee",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"waiting_period" : 0,
"shared_contact" : false,
"request_full_name" : false,
"full_name_type" : "suggestion"
}, {
"email" : "koussai.houssine@universign.com",
"phone_number" : "+33612345658",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"waiting_period" : 0,
"shared_contact" : false,
"fullname_suggestion" : "Koussai HOUSSINE",
"phone_number_suggestion" : "+33612345658",
"full_name" : "Koussai HOUSSINE",
"full_name_type" : "suggestion"
} ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_QPoP",
"name" : "Contract template.pdf",
"name_locked" : true,
"type" : "final",
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_BJMl",
"type" : "label",
"position" : {
"page" : 2,
"x" : 184,
"y" : 238,
"width" : 0,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12
}, {
"id" : "fld_dQE7",
"position" : {
"page" : 2,
"x" : 315,
"y" : 413,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_wao",
"name" : "chkGroup1727258957748",
"type" : "checkbox_group",
"built_in" : false,
"updatable" : true,
"deletable" : false,
"minimum_required" : 0
}, {
"id" : "fld_E4wb",
"name" : "rbtGroup1727258985188",
"type" : "radio_group",
"built_in" : false,
"updatable" : true,
"deletable" : false,
"required" : true
}, {
"id" : "fld_Yn0O",
"name" : "chkField1727258957853",
"type" : "checkbox",
"position" : {
"page" : 2,
"x" : 66,
"y" : 358,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_wao",
"checked" : false
}, {
"id" : "fld_dxb",
"name" : "chkField1727258974301",
"type" : "checkbox",
"position" : {
"page" : 2,
"x" : 66,
"y" : 338,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_wao",
"checked" : false
}, {
"id" : "fld_97z0",
"name" : "rbtField1727258985291",
"type" : "radiobutton",
"position" : {
"page" : 2,
"x" : 75,
"y" : 144,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_E4wb",
"checked" : false
}, {
"id" : "fld_W0q",
"name" : "rbtField1727258985376",
"type" : "radiobutton",
"position" : {
"page" : 2,
"x" : 75,
"y" : 164,
"width" : 15,
"height" : 15
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"parent" : "fld_E4wb",
"checked" : false
} ],
"big_file" : false,
"editable" : true,
"available" : true
} ],
"field_groups" : [ {
"id" : "fld_dQE7",
"type" : "field",
"fields" : [ "fld_dQE7" ]
}, {
"id" : "fld_wao",
"type" : "field",
"fields" : [ "fld_wao" ]
}, {
"id" : "fld_E4wb",
"type" : "field",
"fields" : [ "fld_E4wb" ]
} ],
"instructions" : {
"signatures" : [ {
"signer" : "$1720534563486",
"field" : "fld_dQE7"
}, {
"signer" : "koussai.houssine@universign.com",
"field" : "fld_wao"
}, {
"signer" : "koussai.houssine@universign.com",
"field" : "fld_E4wb"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_8Ja0nDDZMl2Dz",
"actor" : "$1720534563486",
"tasks" : [ {
"type" : "signature",
"field" : "fld_dQE7"
} ]
}, {
"id" : "act_3Q5D78OJr8lk",
"actor" : "koussai.houssine@universign.com",
"tasks" : [ {
"type" : "signature",
"field" : "fld_wao"
}, {
"type" : "signature",
"field" : "fld_E4wb"
} ]
} ],
"action_graph" : {
"start" : [ "act_8Ja0nDDZMl2Dz", "act_3Q5D78OJr8lk" ],
"act_8Ja0nDDZMl2Dz" : [ "end" ],
"act_3Q5D78OJr8lk" : [ "end" ]
},
"metadata" : { },
"carbon_copies" : [ ],
"allow_carbon_copy" : false,
"last_publication_date" : "2024-09-25T10:10:11Z",
"last_publisher" : {
"name" : "John DOE",
"email" : "koussai.houssine@universign.com",
"workspace_name" : "DemoWS"
},
"issuing_entity" : {
"active" : true,
"name" : "DemoWS",
"id" : "iss_xa1LoEebXQM3"
}
}, {
"object" : "template",
"id" : "tpl_wXzwBdJe91Y6",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-02-09T13:45:11Z",
"duration" : 20160,
"template_name" : "Nouveau modèle",
"folder_name" : "Default folder",
"language" : "fr",
"sender_name_display" : "issuing_entity",
"creator" : {
"name" : "Koussai HOUSSINE",
"email" : "koussai.houssine@universign.com",
"workspace_name" : "DemoWS"
},
"state" : "published",
"publishable" : true,
"participants" : [ {
"email" : "jane.doe@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"waiting_period" : 0,
"shared_contact" : false,
"full_name_type" : "suggestion"
} ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_Pdk",
"name" : "Contract template.pdf",
"name_locked" : true,
"type" : "final",
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_gg6M",
"position" : {
"page" : 2,
"x" : 323,
"y" : 419,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
} ],
"big_file" : false,
"editable" : true,
"available" : true
} ],
"field_groups" : [ {
"id" : "fld_gg6M",
"type" : "field",
"fields" : [ "fld_gg6M" ]
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane.doe@universign.com",
"field" : "fld_gg6M"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_8JXr6qM7Q1AqO",
"actor" : "jane.doe@universign.com",
"tasks" : [ {
"type" : "signature",
"field" : "fld_gg6M"
} ]
} ],
"action_graph" : {
"act_8JXr6qM7Q1AqO" : [ "end" ],
"start" : [ "act_8JXr6qM7Q1AqO" ]
},
"metadata" : { },
"carbon_copies" : [ ],
"allow_carbon_copy" : false,
"last_publication_date" : "2024-02-19T09:47:09Z",
"last_publisher" : {
"name" : "Koussai HOUSSINE",
"email" : "koussai.houssine@universign.com",
"workspace_name" : "DemoWS"
},
"issuing_entity" : {
"active" : true,
"name" : "DemoWS",
"id" : "iss_xa1LoEebXQM3"
}
} ]
}
| Parameters | Type | Description |
|---|---|---|
| has more | boolean | If there are more existing templates in the workspace than the templates returned in the response. |
| content | string | The list of templates. |
| content[ ].object | string | The object's type. Value is template. |
| content[ ].id | string | The template ID. |
| content[ ].template_name | string | The name of the tempate. |
| content[ ].folder_id | string | The ID of the folder associated with the template. |
| content[ ].folder_name | string | The name of the folder associated with the template. |
| content[ ].created_at | string | The date the template was created as a draft. Returned format is ISO 8601. |
| content[ ].state | string | The template state. One of draft (unpublished and not yet ready to be used for transaction creation) or published (ready to be used for transaction creation). |
| content[ ].publishable | boolean | Whether the template is publishable or not. |
| content[ ].folder_id | string | The ID of the folder associated with the template. |
| content[ ].issuing_entity | string | Information about the issuing entity of the template. |
| content[ ].issuing_entity[ ].name | string | The issuing entity name. |
| content[ ].issuing_entity[ ].id | string | The ID of the issuing entity. |
| content[ ].issuing_entity[ ].active | boolean | Whether the issuing entity is active or not. |
| content[ ].duration | number | The duration of the transaction created from the template. |
| content[ ].language | string | The language of the future transaction. |
| content[ ].sender_name_display | string | In whose name the transaction created from the template is sent. If the issuing entity feature is activated, possible values are issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). If the issuing entity feature is deactivated, possible values are workspace (the name of the workspace), name_workspace (the name of the person and the name of the workspace), name_email_workspace (the name and email of the person as well as the name of the workspace). Default value is name_email. |
| content[ ].metadata | object | The metadata object. The key-value pairs of this object represent the key-value pairs of the template's metadata. |
| content[ ].metadata.* | string | The metadata entries you associated with the template. Value can be empty if it needs to be filled during the creation of a transaction from the template. |
| content[ ].carbon_copies | array | The emails you want to notify and give access to signed documents when the transaction created from the template is completed. |
| content[ ].allow_carbon_copies | boolean | Whether the user of the template can add carbon copies or not. |
| content[ ].creator | object | Information about the creator of the template. |
| content[ ].creator[ ].name | string | The name of the workspace member who created the template from the web application. |
| content[ ].creator[ ].email | string | The email of the workspace member who created the template from the web application. |
| content[ ].creator[ ].workspace_name | string | The name of the workspace which created the template by API. |
| content[ ].instructions | object | The signature and review instructions for the template. Used to link a signer to a field and a reviewer to a participant. Instructions are automatically updated when a signer or a reviewer is added to the template. |
| content[ ].instructions[ ].signatures | array | Instructions linked to signatures and visas. |
| content[ ].instructions[ ].signatures.signer | string | The signer's email address or designtation (in case the participant is unknown). |
| content[ ].instructions[ ].signatures.field | string | The field that bears the signature or visa instruction, designated by its ID. |
| content[ ].instructions[ ].reviews | array | Instructions linked to reviews. |
| content[ ].instructions[ ].reviews.reviewer | string | The reviewer's email address. |
| content[ ].instructions[ ].reviews.recipient | string | The email address of the participant for whom the review is intended. |
| content[ ].instructions[ ].editions | array | Instructions linked to editions. |
| content[ ].instructions[ ].editions.editor | string | The editor's email address or designation (in case s/he is unknown). |
| content[ ].instructions[ ].editions.recipient | string | The reference of the unknown participant to be edited. |
| content[ ].instructions[ ].captures | array | Instructions linked to captures. |
| content[ ].instructions[ ].sequencing | array | Sequencing instructions between participants. |
| content[ ].instructions.sequencing[ ].before | string | The participant (identified by his/her email) who must perform his/her action before the after participant. |
| content[ ].instructions.sequencing[ ].after | string | The participant (identified by his/her email) who must perform his/her action after the before participant. |
| content[ ].actions | array | The list of actions to perform. The actions array is automatically updated when a signer or a reviewer is added to the template. |
| content[ ].actions[ ].id | string | The action ID. |
| content[ ].actions[ ].actor | string | The email address of the participant having to perform the action. |
| content[ ].actions[ ].url | url | The URL to the participant's action page. |
| content[ ].actions[ ].state | string | The state of the action, amongst open (the participant can perform his/her action), waiting (the participant cannot perform his/her action yet) or closed (the action is completed). Please note that an action can be reopened after it was closed: this happens if the transaction created is updated dynamically with new instructions for the actor. |
| content[ ].actions[ ].stalled | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| content[ ].actions[ ].stalled_at | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| content[ ].actions[ ].stalled_reason | boolean | Value is true if the participant has not completed his/her action within the allotted time. |
| content[ ].actions[ ].tasks | array | The tasks list the participant must complete before the action is closed. |
| content[ ].actions[ ].tasks.field | string | The field ID, if the action type is signature. |
| content[ ].actions[ ].tasks.document | string | The document associated with the current review task. |
| content[ ].actions[ ].tasks.recipient | string | The recipient of the review, if the action type is review. |
| content[ ].actions[ ].tasks.type | string | The task type. Value is signature for a signature or visa task, or review for a review task. |
| content[ ].actions[ ].tasks.state | string | The state of the task. Can be todo (the participant can perform the requested task), skipped (the task no longer needs to be performed) or done (the participant has performed the requested task). |
| content[ ].last_publisher | object | Information about the last publisher of the template. |
| content[ ].last_publisher[ ].name | string | The name of the last publisher of the template. |
| content[ ].last_publisher[ ].email | string | The email of the last publisher of the template. |
| content[ ].last_publisher[ ].workspace_name | string | The workspace name of the last publisher of the template. |
| content[ ].last_publication_date | string | The date the template was last published. |
| content[ ].participants | array | The list of participants within the transaction. This array is automatically updated when a signer or a reviewer is added to the transaction. |
| content[ ].participants[ ].email | string | The email address of the participant. |
| content[ ].participants[ ].designation | string | The designation of the unknown participant. Max 250 characters. |
| content[ ].participants[ ].description | string | The description of the unknown participant. Max 250 characters. |
| content[ ].participants[ ].invitation_subject | string | The subject of the participant's invitation email. Max 100 characters. |
| content[ ].participants[ ].invitation_message | string | The participant's invitation message. Max 1000 characters. |
| content[ ].participants[ ].reminder_subject | string | The subject of the participant's reminder email. Max 100 characters. |
| content[ ].participants[ ].reminder_message | string | The participant's reminder message. Max 1000 characters. |
| content[ ].participants[ ].signed_documents_subject | string | The subject of the email sent to the participant when signed documents are available. Max 100 characters. |
| content[ ].participants[ ].signed_documents_message | string | The message sent to the participant when signed documents are available. Max 1000 characters. |
| content[ ].participants[ ].name_constraint | string | The participant full name that must be used in the transaction. (Deprecated) See full_name and full_name_type. |
| content[ ].participants[ ].fullname_prerequisite | string | The participant full name that must be used in the transaction. (Deprecated) See full_name and full_name_type. |
| content[ ].participants[ ].fullname_suggestion | string | The participant full name suggestion that can be used in the transaction. (Deprecated) See full_name and full_name_type. |
| content[ ].participants[ ].full_name | string | The participant full name as it will display in the signature. |
| content[ ].participants[ ].full_name_type | string | The participant's full name type. One of suggestion or prerequisite. |
| content[ ].participants[ ].request_full_name | boolean | Value is true if the full name of the unknown participant is requested. |
| content[ ].participants[ ].phone_number_flex_constraint | string | The participant mobile number that must be used for authentication when the minimum requested signature level is level1. (Deprecated) See phone_number and phone_number_type. |
| content[ ].participants[ ].phone_number_flex_prerequisite | string | The participant mobile number that must be used for authentication when the minimum requested signature level is level1. (Deprecated) See phone_number and phone_number_type. |
| content[ ].participants[ ].phone_number_suggestion | string | The participant mobile number that is suggested for authentication, but can be modified by the participant (or by Universign if the participant owns a certificate linked to a different mobile number.). (Deprecated) See phone_number and phone_number_type. |
| content[ ].participants[ ].phone_number | string | The participant mobile number that is used for authentication. |
| content[ ].participants[ ].phone_number_type | string | The participant's mobile number type. One of suggestion, flex_prerequisite or prerequisite. |
| content[ ].participants[ ].request_phone_number | boolean | Value is true if the phone number of the unknown participant is requested. |
| content[ ].participants[ ].stall_trigger | int | The allotted time, expressed in hours, for the participant to complete his/her action, from the moment his/her action is open. If the participant is still inactive after that period, the participant action is flagged as stalled and so is the transaction. |
| content[ ].participants[ ].ongoing_conversation | boolean | Whether there is an ongoing conversation between the participant and the transaction creator. |
| content[ ].participants[ ].has_unread_message | boolean | Whether there is at least one unread message in the conversation. Can be true only if ongoing_conversation is true. |
| content[ ].participants[ ].schedule | array of int | The emailing schedule of the participant, expressed in hours. |
| content[ ].participants[ ].do_not_invite_before | date | The date and time after which the invitation is sent to the participant. |
| content[ ].participants[ ].min_signature_level | string | The minimum required level of signature for a participant among: level0 (simple signature without authentication), level1 (simple signature), `level2 (advanced signature), level3(advanced signature with qualified certificate) and level4 (qualified signature). |
| content[ ].participants[ ].waiting_period | number | The duration in days of the reflection period before the participant can sign his/her documents. |
| content[ ].participants[ ].shared_contact | boolean | Whether the participant is a shared contact or not. |
| content[ ].sealers | array | The list of seals. |
| content[ ].sealers[ ].id | string | The moral person's certificate ID. |
| content[ ].sealers[ ].name | string | The seal common name. |
| content[ ].documents | array | The documents added to the template. |
| content[ ].documents[ ].id | string | The document ID. |
| content[ ].documents[ ].name | string | The name of the document, if you set any. If not, the file name is used. |
| content[ ].documents[ ].editable | boolean | Whether the document is currently updatable or not. |
| content[ ].documents[ ].updatable | boolean | Whether the document is currently updatable or not. |
| content[ ].documents[ ].deletable | boolean | Whether the document is currently deletable or not. |
| content[ ].documents[ ].fields | array | The list of all fields associated with the document. |
| content[ ].documents[ ].fields[ ].id | string | The field ID. |
| content[ ].documents[ ].fields[ ].name | string | The name of the field. |
| content[ ].documents[ ].fields[ ].type | string | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| content[ ].documents[ ].fields[ ].built_in | boolean | Whether the field is built-in the PDF. |
| content[ ].documents[ ].fields[ ].consents | array of strings | Mandatory consents to agree to when signing or reading the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| content[ ].documents[ ].fields[ ].optional_consents | array of strings | Optional consents to agree to when signing or reading the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Displays only if field type is signature or visa. |
| content[ ].documents[ ].fields[ ].updatable | boolean | Whether the field is currently updatable or not. |
| content[ ].documents[ ].fields[ ].deletable | boolean | Whether the field is is currently deletable or not. |
| content[ ].documents[ ].fields[ ].position | object | The position of the field on the document. |
| content[ ].documents[ ].fields[ ].position.page | int | The page number on which the field is positioned. |
| content[ ].documents[ ].fields[ ].position.x | int | The field horizontal coordinate on the document page (in pixels). |
| content[ ].documents[ ].fields[ ].position.y | int | The field vertical coordinate on the document page (in pixels). |
| content[ ].documents[ ].fields[ ].position.width | int | The field width (in pixels). Default value is 200. |
| content[ ].documents[ ].fields[ ].position.height | int | The field height (in pixels). Default value is 19 . |
| content[ ].field_groups | array | The list of field groups in the template. |
| content[ ].field_groups[ ].id | string | The signable group ID. |
| content[ ].field_groups[ ].type | string | The signable group type. Possible values are field if there is only one field in the signable group or group if there are more than one. |
| content[ ].field_groups[ ].fields | object | The list of fields in the signable group. Displays only if the signable group type is group. |
| content[ ].action_graph | array | The list of actions as a graph. Defines the order between the actions to be performed by participants. |
| content[ ].action_graph[ ].start | array | List of the first actions to be performed in the template. |
| content[ ].action_graph[ ].** | array | List of the actions already performed in the template. |
Create a transaction from a template
POST /v1/transactions/template
This endpoint enables you to create a transaction from a preconfigured template. Note that, by default, only the template_id parameter is required. All other parameters are optional, unless they are requested by the template creator.
Note that you can only create a transaction from a published template.
Request example
curl https://api.universign.com/v1/transactions/template \
\
-d template_id=tpl_agMgvOzLya3k \
\
-d folder_id=fol_JxmJlV5P922X \
\
-d name=Contract John \
\
-d participants[$1707755519455].email=john.doe@universign.com \
\
-d documents[doc_LwmW].file=file_5XKzyVPLrv41ClDmDlVyKdvey \
\
-d documents[doc_LwmW].name=Contract template.pdf \
\
-d fields[fld_BJDO].x=255 \
\
-d fields[fld_BJDO].y=164 \
\
-d fields[fld_BJDO].page=1
| Arguments | Type | Description | |
|---|---|---|---|
| template_id | string | required | The ID of the template used to create the transaction. |
| name | string | optional | The name of the transaction. |
| expires_at | string | optional | The required expiration date of the transaction. Expected input format is ISO 8601 (ex: 2021-10-14T17:32Z). The maximum duration of a transaction being 60 or 180 days, you can set its expiry date to current date + 67 or 187 days depending on the workspace entitlements (the 7 extra days correspond to the maximum period in draft state). |
| metadata[*] | string | optional | The value of the metadata key specified in the used template. The value of the metadata key must be appended to the metadata field between brackets (for example metadata[doc_type]), and must not exceed 20 characters. Please note that square brackets ([ or ]), equal sign (=), plus sign (+) and underscore (_) and are unsupported characters in the value of the metadata key. The metadata value must not exceed 200 characters. |
| folder_id | string | optional | The folder in which you want to create the transaction, identified by its ID. By default, the transaction is created in the workspace default folder. |
| carbon_copies | array | optional | The emails you want to notify and give access to signed documents when the transaction is completed. |
| autostart | boolean | optional | Whether the transaction must be started automatically or not. Default value is false. |
| participants[id] | array | optional | The unknown participants of the transaction. |
| participants[id].email | string | optional | The unknown participant's email. |
| participants[id].full_name | string | optional | The unknown participant's full name. |
| participants[id].phone_number | string | optional | The unknown participant's phone number. |
| documents[id] | array | optional | The documents of the transaction. To be set, only if the used template contains a specimen. |
| documents[id].file | string | optional | The file ID of the final document to replace the specimen of the template. |
| documents[id].name | string | optional | The name of the final document to replace the specimen of the template. Cannot be set if the specimen name is locked by the template creator. |
| fields[id] | array | optional | The fields of the transaction to be repositioned. |
| fields[id].page | string | optional | The page number on which you want to position the field. |
| fields[id].x | string | optional | The field horizontal coordinate on the document page (in pixels). |
| fields[id].y | string | optional | The field vertical coordinate on the document page (in pixels). |
Returns
The request returns a transaction object.
Response example
{
"object" : "transaction",
"id" : "tx_DdLq4OvLXwyd",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-02-12T16:40:03Z",
"started_at" : "2024-02-12T16:40:04Z",
"expires_at" : "2024-02-26T16:40:04Z",
"name" : "Contract",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "fr",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "started",
"participants" : [ {
"email" : "john.doe@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6A4Q",
"name" : "Specimen 1",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_mEZr",
"position" : {
"page" : 1,
"x" : 255,
"y" : 164,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
} ]
} ],
"instructions" : {
"signatures" : [ {
"signer" : "john.doe@universign.com",
"field" : "fld_mEZr"
} ],
"reviews" : [ ],
"captures" : [ ],
"sequencing" : [ ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_oXMk58w6Yaako",
"actor" : "john.doe@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_oXMk58w6Yaako",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_mEZr"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"max_expiry" : "180_days",
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_w9nmLe9qzYDy",
"name" : "Test_entity",
"lock_sender_name_display" : false
},
"private" : false
}
Full transaction request
It is possible to create a full transaction in a single API request. To do so, you must pass a json as a request body, with the following parameters:
Request example
curl https://api.universign.com/v1/transactions/full
\
-d "{
"autostart": true,
"metadata": {
"siren": "123456"
},
"name" : "My full transaction request",
"language" : "en",
"duration": 15500,
"private" : false,
"documents" : [{
"content" : "JVBERi0xLjUKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nFWNzQrCQAyE73mKOfcQk/3pZkE8CHovLPgCWkWqYC++vlsWFmQuQ2bmi7DiSx8IhMUZYo7sQoIFZRsV640uA96k2LTeSVpkGS/6K9fL0ucNtnTs5nqLHjQP7WdVZR4LOZfY54jRZ46GcsXurLDE2RLKvBcVJ17CoTzpVGiiCT/8niaKCmVuZHN0cmVhbQplbmRvYmoKCjMgMCBvYmoKMTMzCmVuZG9iagoKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyL0ZsYXRlRGVjb2RlL0xlbmd0aDEgNzk2MD4+CnN0cmVhbQp4nOVYfXQU13W/d2ZXq0ESu8KAZdb2PnkMheoLJOMAxtYiaRepEpGEULyLDNJod6VdkHbXOwMYOykiX4Y1FOwStw7pgXNqt8HGYQTYCCcuqpuT1ImpfVL79PS4KbLrpHZjqtSxc1oT2N73ZlYIBXN60v7Xt5qZ++7n79173/AGI7MtBsUwAjL4I8Naeq7TIQHAawA4J7LdYHLrW4uIngCQ9gykB4e/eeaBjwEccQDX6cGhnQNlvdv/E6D4VgD5aDymRS/3/EUlgPt75OPuODG6rnzZRXOygTvjw8ZDV6SR2QCeMprPGUpFtDGpgUgP2UDxsPZQukG+leJ7VtCcJbXh2GDRI/NoHgIo6kmndONJGM8BeE9zeToTS+9rOTVG8zcpfiPxkH58FBNZwOeS7ID/z8P5mvM1+JJzN8yDneJ+zXCsgrmwAyD3IZ9dvV+5//8WRaH1OA0vwwk4eo1oD/wh3Y9fwzsHfwPPCeow7L+B27PwrE0dgqfg0c/U2wJfIT9Pw+lpvD7i7oQ/pchj8JfUKHdgHUXdakvfhlev7wrfwVfhCfg2aT4BZ+h+mHbGI9JH8IS0HpLSP8i74cuwl9Z4BBNwgPT74Gnsgc3EtcZmiEFqhtMsHIRn4GHahVPDuTv3Kyj5zSlCvpf8PAkJeJAq6f7N7bmP4C7Hz6HkyptwTvYR9u/AC8Jkd97W1SxvkV6UpMt/TJPHYZAuDf+RcO6X19wgm//rUbCb3gtzHT/mPZT7+yu7CPvbVKGXKBuv+9f2bAyHujd0re/saP/8urbWP2hpXhsMNDU2rPHX33fv6ntWrVzxubuXL1taU11Vufj3Fi28U72j3Fc2t9Tjnl1SNEspdBU4HbKEUMlM7AuY8kJWGtTUgKo1V1WyQFm8qaoyoAb7TKYxkx6ORWpzs2Cpmsn6mLmIHto0dp/pJ82BGZp+S9M/pYkethpW8xAqM883qWwMN3aGiN7fpIaZeVHQ6wTtWCQmJTQpLycLgYqjZQEzuD2eDfQRRhwtmtWoNsZmVVXC6KwiIouIMher6VFcfB8KQlocWDUqQWEJD0srDWhRs6MzFGjylpeHqypbzNlqkxBBo3BpFjSaLuGSJTh0eIyNVo5n9415oL+vojiqRrUHQqaskW1WDmSzj5qlFeYStclc8vB7ZbTymFmpNgXMCu61df1UnNarIdF0LvSoLPsJ0HLUix9ey9FsTsFCzyfASVNqNHF9qJwPb5Bync0GVRbM9mW1sdxIv8o8ana0uDibDlC6oSNELsZyLz3mNYP7wqanL46rwvbSg+tbzZs6e0KmtDDI4hpx6K9eLV/hLS+d0un4LDFQWig5lOHycp6Gx8b80E8Tc6QzZM0Z9HtPgr+mImxKfVwynpfM6+aSkbxkyrxPpdq2doWypmNhS1QNUMYf08yRfuquLbwwqsec/WtvuZqdU8pW1oSFLiNULdEEM52LKElkNd2A+oabZD1iMvvX1uOilwIsKp3DVqrkhvsJqIE++297vIwcMEp0c4XVCBtCpr+JCL9mVywwurSGLLQ+KliiSRTTrFHT5ly1Yaq6HFYg0RUSJraZObfRhL6IbWXWBMS+YoFsX5MFgftSO0NnoS43MXoX856qg7sg3MSV5zdSly0KZEPRAdPX543SvhtgIW+56Q9ThcNqKBbmbUcZWjLhFc0RFr2yIdTapbZ2bgytsIFYAu7OsTAww40a8lpuqAHNwoWFLCR55TApeojBgkSoDavpbroWFtLloYQLLm/chtUshF7IaxMMcwkLxJpsPT6/xqmTt1Njc95bAZ+Sn8Zmb3m43BpVlRKJmR2YLAp5UpvzInpNkaCQ+rOxWbB4Lst407OQGlPDapyZ/o4QXxtPj8iynQyRc7tWG66ZTUsWpQnKSZyf8GSawQrv9OSaa8V8ato8Q9ySF7NsodraleXOVdshEPIWE3gL+1eUesW7gG9old69zENbWmzo7KjfzzdzfBV3orZEs2pXaLXQpvfJl7wP81hzoBVbNzRUVdKrrWFUxT2do37c07UxdNZDZ7k9G0InJZQa+xrCo3eSLHSWAfgFV+JczuQTxifc03qaFAp971k/wIiQOgRDzCNjCIJXmOchRMYki+exAi0SgfwgkcRhSfx5bQfxCi3eiOCJMQo8Zf5ZTn+hX/EXSyWSdxQ56yRxXqKzp4JwqhhL0DtKVusFewxHRhW/19IYIQ2/hXBP99XQ3RtDp4qBzMSdAjXwQe1SFqdi0z8rARbljfLFcDzbF+abDeZTaegPTVTvozKp9xGQgmJzlhprMIvUBs6v5/x6i1/A+S5qUZyPZD5Cte8wkXdAT6ictiRb8Ko367nIKxWml0rW87MqAneeTiK1dG6UwQU+f4lU4JQLZKXQSadqGerP15wvnYMrV5bWldYtW3pTeWn5TaXlpecdsUuH2+Tzzt2f7nIuv3Sz4wN+OEA6M4GTka8iyPhvdsmyg06FRY6i4hKX1BvucOGEC11juXf81Te17HTtdUluFxa6XAqPNYeV4HgJmiV4tARHSjBdgn0l2FGCxN9kjwehvra+bmXN5k2bKjY9WDEFzAJH2EpVIsvpcmiXC86dkz49J+2/rDt3Xz4ubfh0F8co0VkL8F46Z/H1Jv3NsssFDkeh4nQ75iF0hRFyCk4oeEHBcQVNBY8oOKJgWkEfFV7BX04THVXwoILtQrTpQWtkpgbUV0BZfT1HWVpnpW953TyZ0O09ffq0kx0//umEY9WlH+Ry+dOVpwCcAuNZwrjLqgm+588RRsnhUAoZohtxtoxOv8P5rR6HJD+h4FcVzCjYr+AGBZsUrFXwDgXnKuhQ8CMF31XwTQW/r+BJBZ9W8FBeP5rXv0vBO/P6gx8reFbBYwo+peBeBXcq2KLgvQpWiSW6FaTcTCr4toI/VvC7Cj6n4J8puF/BLymYUrBXwVYF71GwQkGvgkUKXlbwooI/VfB8Xv+wgo8J/a0K9ii4TvhfouAtQv9zlxT8xbUGTyn+HhtMQphYIQjSbQpyZQvNOQVPiGI9IlxPgSDQ0utCTLIDCu5SsI/2Z35Brs355trU++C00Zu5dlxVy/fijPE/04X6mgpYUOb5u15SmtYZqMp1MnUHDh4q+/4PXsH98sef7nr1VRDfutItT339mZ4/6XWv/gR81nfW3/r/65vTz+W0g+l7nj7CJJtBdq77rnweGqdUcMZR3kEfz+edP4Rv4w9hr7QS+LcWH4vgIXgFfoRvCAsnfWdbPiXwQA08QMTTkoPenVx6Oyan/N4/FQPBTTO0rVwwYNMyLIBhm3aQzqM27YQS+vqx6AKYDX9u0y76Xhq16UKYixU2rcBsrLfpWZjAdTZdBLdKL07970C19BObLoHlch7bbFggLyck1O40+47cbtMIt8uXbVqC2Q6vTcv0JbbEph1wu2OTTTthgeMRmy6AWx3fsGkXfOwYtelCWOx8xqYVuNV53qZnST9xfmDTRbCi8Ls2XQwPFP7Kpktgi5LHNhvuUs42JQYTRuLhWJRFNUNjkVR6ZyYxGDfY4sgSVrt02VK2NpUaHIqxxlQmncpoRiKVrGazGmfq1bL15KNZMypZSzJS3Zboj1nKrEtL6utjg9uGtMwaPRJLRmMZVsVmKMyYfiGW0TldW72seulV2QzNhE6fbEZGi8aGtcxWlhq4FgPLxAYTuhHLEDORZN3VXdWsQzNiSYNpySjbMGXYPjCQiMQEMxLLGBopp4w4wdyyLZPQo4kIj6ZXT6GfloouI7Y9xtZphhHTU8kGTadYhGxNJjGcqmQ74olInO3QdBaN6YnBJAn7d7JrbRhJNVpLMpnaTi63xyoJ90AmpscTyUGm04qZHsskBmwXzIhrBl/5cMzIJCLa0NBOKtpwmkz7qUo7EkacR9eGnq22UFBaBiibLDGczqS2C3hVeiQTiyUpjhbV+hNDCYN8xLWMFqFkUcYSEV0kg3LA0lqyKrAtk0rHCOT9a9uuKhIsK5F6amh7TBfayVgsqvNCRGmJQ2REgYdSqa18KQOpDMGLGvGqaXgHUkmDTFNMi0ZpzZSoVGTbMC8RZdjIg9MimRTJ0kOaQV6G9eq4YaRX1dTs2LGjWrOrEqGiVJPnmhvJjJ3pmF2KDPcyPNRGlU/yqm0TpeWL6GppY+1pyk+QwDFboZLle3JZ9TI7BKUxkTb0aj0xVJ3KDNa0B9ugCRIwSJdB18MQgygwujSaa0RFIAVp2AkZoRUnLoPFxF1Cz1pYCsvoYrCWtFIkHyJ7Rq/aFOmnxV0TflOQhGqSzBKyG/urJWq9jaNZ2FcS1UIeIuSjjez6STrdM4MumiVBF3aDsI1waKSxhjgR4iTJF7dgUEXXjT3cWPoFIdGn+LWEaBldS69rd2OfCZIwkWNDSDjGYYF7K/FS9I/FjfLASC8m6qaTJCZmUeGV++4mjS6h1SEseQ4MES0ptDZcJ2I7RRwg+4ioYV4zInzzXrA8p4iO29ncQpnOCARRYZdfm06Rfzv31++KLoFuu4i5TvD5XBeyBprr9rqsnK0R8YZpxnOxg5DwuHFBayKfUWHNeytpW/ZTt7EbxmG2rWbXJUm/FOlaKLlNpZ3vAXHXRdwkxWBEWzVmAilHNzADBRMZ00T+rZoPk9QQuhHiD9Fvp73Thik/VtR+ey/tEDszPrV20i+/Q1T2ai6sbhmwe5MJbprolMCez16VqAjHHxOoOKWJnd5PFkMijoUjLnpCExWN2RU2BNp8lqL2qjjCtOBUQUB0A9/dMTuT99N7oe26Hq1sTe9IXokhgVef5jsp0EYFLzWVWa41ZEeyVjwk3j9bp6oyILrMyl5UeKv6jPwOiNwYdtSUQBSln1Vnq6NSZLtNVM3aRVYPG7+VOU3kN2XbpcVbyLCxDItdERd9l4ZVdICsIXT8Vy26b/peidg7pdrGXPM723FcaZHB6bsiM4VlmDC22Xs+ObXXtk3btflKdNGbp028JdJ2/wTtzLEZHvhemfmeXCbek9euwurGBM0NgUcXuawWaxgkeTtFaONnZTFyL9PJ+DpjTTl9itIZGFdCN95nPxvQD3PBh2vo6aPnPVCHq4i/gp4kBz+66JzrE/cj6PA/i+OX8cRlhMs4q/0Sskv4Scdi30fBxb7/CP6+75fBCl/v5K5JyT3ZPtk7eWDyxKSz6Gfv3e77l3eDPve76H83ON/3zkTQ9/rEhYnJCdk/UXd3cCJY5vv3iznfRXy/+8PmX3T/Wy10f/D++93/2gzdP4ec76f3Xui+gHL3P98rd/+TnPO53/K9JYmb/0dl3uDrr+DL46t9f92xyPe9v1rsy53FjrH02MiYPJYb9+fG5tQGfWfqz7SfSZ3ZdebImRNnXGUvYvrk0ZPmSdl9Eg++gOYL6H4BC92n6k9NnpJHzIOmZJrj5humXHOi/oR09HnzeWn8+Teel2qO1x+XjjyH48++8azUfuzAManmWOrYuWO5Y45vHb7T13EYU0/iuSfxyeBtvm8cutnnPuQ7tOvQgUO5Q86lj/sfl0Yex/SBkQPSwQM4fuCNA1L7vt59qX3y14M535Gv4Ve/ssxn6PU+nRaSSq72JYPLfQuwrPuWurJuV53cXUBL7yNZL10PBJf5ejY2+zbS86baOd1OSo+jVu4ekrFYXi23yUPyF2XnZGfOH+2U/J3LVwT9nQsXB1/vwJYg8zWT57V0nQjiheBkUBoJ4vzaed2l6O721Lq7JaT6A/p87np3r3uX2+F217jb3Sn3AfcFd87tqifepFtOAbYDjsxHJ47hwdENXRUVrWOu3PpW09XRY+Iec2EXv/s7N5oFe0zo3tgTGkX8o/DX9u+HhttazdqukNl3W7jVjBLh58QIEZ7bRudDQ1g3dGNbBR9oEWBUVOg6p5DPKiyZoLBCJzGpkRFNjG2gV+gG6jptFoP4Om4mWqdXDfF1+iIkJVKx/U95ogCbyRHdDCuErpOdTn50O1zZZvhve+giqAplbmRzdHJlYW0KZW5kb2JqCgo2IDAgb2JqCjQ0NjYKZW5kb2JqCgo3IDAgb2JqCjw8L1R5cGUvRm9udERlc2NyaXB0b3IvRm9udE5hbWUvQkFBQUFBK0xpYmVyYXRpb25TYW5zCi9GbGFncyA0Ci9Gb250QkJveFstNTQzIC0zMDMgMTMwMCA5NzldL0l0YWxpY0FuZ2xlIDAKL0FzY2VudCA5MDUKL0Rlc2NlbnQgLTIxMQovQ2FwSGVpZ2h0IDk3OQovU3RlbVYgODAKL0ZvbnRGaWxlMiA1IDAgUgo+PgplbmRvYmoKCjggMCBvYmoKPDwvTGVuZ3RoIDI0MS9GaWx0ZXIvRmxhdGVEZWNvZGU+PgpzdHJlYW0KeJxdUEFqwzAQvOsVe0wPQbJjSgtGEFICPqQtdfsAWVq7gloSa/ng31dS0hZ6kJhhdobZ5afuqXM28lfyuscIo3WGcPEraYQBJ+tYVYOxOt5Y+fWsAuPJ229LxLlzo29bxt+StkTaYHc0fsA7xl/IIFk3we7j1CferyF84YwugmBSgsEx5VxUeFYz8uLadybJNm77ZPkbeN8CQl14da2ivcElKI2k3ISsFUJCez5Lhs7805qrYxj1p6I0WaVJIZoHmXBd8P1jxoeCjyLjpuC6Knk3Z07Oq/80Br0SpbblPqVmLmgd/p4w+JBd5X0Dun10aAplbmRzdHJlYW0KZW5kb2JqCgo5IDAgb2JqCjw8L1R5cGUvRm9udC9TdWJ0eXBlL1RydWVUeXBlL0Jhc2VGb250L0JBQUFBQStMaWJlcmF0aW9uU2FucwovRmlyc3RDaGFyIDAKL0xhc3RDaGFyIDQKL1dpZHRoc1s3NTAgNzIyIDIyMiAyNzcgMjc3IF0KL0ZvbnREZXNjcmlwdG9yIDcgMCBSCi9Ub1VuaWNvZGUgOCAwIFIKPj4KZW5kb2JqCgoxMCAwIG9iago8PC9GMSA5IDAgUgo+PgplbmRvYmoKCjExIDAgb2JqCjw8L0ZvbnQgMTAgMCBSCi9Qcm9jU2V0Wy9QREYvVGV4dF0KPj4KZW5kb2JqCgoxIDAgb2JqCjw8L1R5cGUvUGFnZS9QYXJlbnQgNCAwIFIvUmVzb3VyY2VzIDExIDAgUi9NZWRpYUJveFswIDAgNTk1LjI3NTU5MDU1MTE4MSA4NDEuODg5NzYzNzc5NTI4XS9Hcm91cDw8L1MvVHJhbnNwYXJlbmN5L0NTL0RldmljZVJHQi9JIHRydWU+Pi9Db250ZW50cyAyIDAgUj4+CmVuZG9iagoKMTIgMCBvYmoKPDwvQ291bnQgMS9GaXJzdCAxMyAwIFIvTGFzdCAxMyAwIFIKPj4KZW5kb2JqCgoxMyAwIG9iago8PC9Db3VudCAwL1RpdGxlPEZFRkYwMDUwMDA2MTAwNjcwMDY1MDAyMDAwMzE+Ci9EZXN0WzEgMCBSL1hZWiAwIDg0MS44ODkgMF0vUGFyZW50IDEyIDAgUj4+CmVuZG9iagoKNCAwIG9iago8PC9UeXBlL1BhZ2VzCi9SZXNvdXJjZXMgMTEgMCBSCi9NZWRpYUJveFsgMCAwIDU5NSA4NDEgXQovS2lkc1sgMSAwIFIgXQovQ291bnQgMT4+CmVuZG9iagoKMTQgMCBvYmoKPDwvVHlwZS9DYXRhbG9nL1BhZ2VzIDQgMCBSCi9PcGVuQWN0aW9uWzEgMCBSIC9YWVogbnVsbCBudWxsIDBdCi9PdXRsaW5lcyAxMiAwIFIKPj4KZW5kb2JqCgoxNSAwIG9iago8PC9DcmVhdG9yPEZFRkYwMDQ0MDA3MjAwNjEwMDc3PgovUHJvZHVjZXI8RkVGRjAwNEMwMDY5MDA2MjAwNzIwMDY1MDA0RjAwNjYwMDY2MDA2OTAwNjMwMDY1MDAyMDAwMzYwMDJFMDAzND4KL0NyZWF0aW9uRGF0ZShEOjIwMjAxMTAzMDkzNDAxKzAxJzAwJyk+PgplbmRvYmoKCnhyZWYKMCAxNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDU1NzkgMDAwMDAgbiAKMDAwMDAwMDAxOSAwMDAwMCBuIAowMDAwMDAwMjIzIDAwMDAwIG4gCjAwMDAwMDU5MTMgMDAwMDAgbiAKMDAwMDAwMDI0MyAwMDAwMCBuIAowMDAwMDA0NzkzIDAwMDAwIG4gCjAwMDAwMDQ4MTQgMDAwMDAgbiAKMDAwMDAwNTAwOCAwMDAwMCBuIAowMDAwMDA1MzE4IDAwMDAwIG4gCjAwMDAwMDU0OTIgMDAwMDAgbiAKMDAwMDAwNTUyNCAwMDAwMCBuIAowMDAwMDA1NzQ4IDAwMDAwIG4gCjAwMDAwMDU4MDQgMDAwMDAgbiAKMDAwMDAwNjAxMiAwMDAwMCBuIAowMDAwMDA2MTEzIDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSAxNi9Sb290IDE0IDAgUgovSW5mbyAxNSAwIFIKL0lEIFsgPDgyNkY1QzhGRDlBNzRCMkM0MzNFODAzN0I0RUI1MkY0Pgo8ODI2RjVDOEZEOUE3NEIyQzQzM0U4MDM3QjRFQjUyRjQ+IF0KL0RvY0NoZWNrc3VtIC8yMDBEREQ0NzMwMzI0Q0Q0QTJFMjlGRUNBODQxMjhBQwo+PgpzdGFydHhyZWYKNjI4MAolJUVPRgo=",
"name" : "MyDoc",
"fields" : [
{
"id" : "field_id_1",
"name" : "signature field",
"page" : 1,
"x" : 150,
"y" : 275,
"type" : "signature",
"consents" : [ "I hereby accept the terms and conditions stated in this document!" ],
"optional_consents" : [ "I accept to fill a satisfaction form once the signature process is completed!" ]
},{
"id" : "field_id_2",
"name" : "text field",
"page" : 1,
"x" : 175,
"y" : 200,
"type" : "text",
"tooltip" : "Please enter your ID card number here!",
"width" : 200,
"height" : 50
}],
"initials_fields" :
{
"y" : 15,
"alignment" : "center"
}
}],
"signatures" : [ {
"field" : "field_id_1",
"signer" : "signer@domain.com"
}, {
"field" : "field_id_2",
"signer" : "signer2@mail.com"
}],
"reviews" : [ {
"recipient" : [ "signer@domain.com" ],
"reviewer" : "reviewer1@mail.com"
}, {
"recipient" : [ "signer2@mail.com" ],
"reviewer" : "reviewer2@mail.com"
} ],
"sequencing" : [
{
"before" : ["signer@domain.com"],
"after": ["signer2@mail.com"]
}],
"participants" : [
{
"email" : "signer@domain.com",
"schedule" : [0],
"full_name" : "Jane Doe",
"full_name_type" : "prerequisite",
"invitation_subject" : "This is an invitation subject",
"invitation_message" : "This is an invitation message",
"min_signature_level": "level2",
"signature_image": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAADTED8xAAADMElEQVR4nOzVwQnAIBQFQYXff81RUkQCOyDj1YOPnbXWPmeTRef+/3O/OyBjzh3CD95BfqICMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMK0CMO0TAAD//2Anhf4QtqobAAAAAElFTkSuQmCC"
},{
"email" : "signer2@mail.com",
"schedule" : [0]
},{
"email" : "reviewer1@mail.com",
"schedule" : [0]
},{
"email" : "reviewer2@mail.com",
"schedule" : [0]
}],
"carbon_copies" : ["CC1@mail.com"],
"carbon_copy_subject" : "This is a CC notification subject",
"carbon_copy_message" : "This is a CC notification message"
}
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | optional | The name of the transaction. If not provided, the transaction ID generated by Universign will be used. |
| metadata | string | optional | You can add metadata as a key-value pairs. The key must must not exceed 20 characters. Please note that square brackets ([ or ]), equal sign (=), plus sign (+) and underscore (_) and are unsupported. The value must not exceed 200 characters. You can pass up to 15 metadata entries. |
| duration | int | optional | The required duration of the transaction before it expires, expressed in minutes. Default value is 20160 (14 days). Note that the countdown to expiration starts when the transaction is started, not when it is created as a draft. Do not pass this parameter if you pass the expires_at parameter. |
| expires_at | date | optional | The required expiration date of the transaction. Expected input format is ISO 8601 (ex: 2021-10-14T17:32Z). Do not pass this parameter if you pass the duration parameter. |
| language | string | optional | The language of the transaction. This parameter defines the language of the emails sent to participants and the language of the signature page. Expected input format is ISO 639-1. We currently support 11 languages: Bulgarian (bg), Catalan (ca), Dutch (nl), English (en), French (fr), German (de), Italian (it), Polish (pl), Portuguese (pt), Romanian (ro) and Spanish (es). French (fr) is the default language. |
| carbon_copies | array of strings | optional | The emails you want to notify and give access to signed documents when the transaction is completed. |
| carbon_copy_subject | string | optional | The subject of the carbon copy notification email. Max 100 characters. |
| carbon_copy_message | string | optional | The carbon copy notification message. Max 1000 characters. We support text format or xml with authorized xhtml tags only. For more details, refer to add someone in copy. |
| autostart | boolean | optional | Whether the transaction must be started automatically or not. Default value is false. |
| private | boolean | optional | Set to true if you want the transaction to be seen only by you and members with admin rights. Default value depends on your workspace preferences. |
| watchers | array of strings | optional | Workspace members you want them to follow the transaction, identified by their emails. |
| sender_name_display | string | optional | In whose name the transaction is sent. If the issuing entity feature is activated, possible values are issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). If the issuing entity feature is deactivated, possible values are workspace (the name of the workspace), name_workspace (the name of the person and the name of the workspace), name_email_workspace (the name and email of the person as well as the name of the workspace). Default value is name_email. When the transaction is created by API, the only possible values are workspace or issuing_entity. |
| issuing_entity_id | string | optional | The ID of the issuing entity of the transaction. If you dont set the issuing_entity_id, the transaction will be sent on behalf of your workspace default issung entity. |
| evidence_archiving_configuration_id | string | optional | The ID of the evidence files archiving configuration. To be retrieved from your workspace. For more information about archiving configuration, refer to Archive evidence files. |
| documents | array of objects | required | The transaction's documents. |
| documents[ ].content | string | required | The base64-encoded PDF. Must not be passed if the document file_id is set. |
| documents[ ].file_id | string | required | The file ID of the document (you can only pass this parameter if the PDF was previously uploaded to Universign). Must not be passed if the document content is set. |
| documents[ ].url | string | required | The URL of the document. Must not be passed if the document content or file_id is set. Make sure the URL leads to the document itself and not to its location. The feature needs to be activated on your workspace. |
| documents[ ].id | string | optional | A temporary document ID, defined on your side. Will be replaced by a Universign document ID once the request is sent. |
| documents[ ].name | string | optional | The document name. This parameter is required if the document is passed in base64. If the document is passed via a file ID, the default name will be the name of the file as uploaded to Universign. You can ovewrite the default name by passing a new name value. |
| documents[ ].archiving_configuration_id | string | optional | The ID of the signed documents archiving configuration. To be retrieved from your workspace. For more information about archiving configuration, refer to Archive signed documents. |
| documents[ ].fields | array of objects | required | The list of fields in the document. |
| documents[ ].fields[ ].id | string | required | The temporary field ID, defined on your side. Will be replaced by a Universign field ID once the request is sent. |
| documents[ ].fields[ ].name | string | optional | The name of the field. Note that the field name is required for checkbox_group, checkbox, radio_group, radiobutton and dropdown field types. |
| documents[ ].fields[ ].type | string | optional | The type of the field. Possible values are signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you added an empty text field to be filled by the participant during the signature process), label (if you added a read only text on the document), checkbox_group (if you added a checkbox group), checkbox (if you added a checkbox), radio_group (if you added a radio button group), radiobutton (if you added a radio button), dropdown (if you added a dropdown list). |
| documents[ ].fields[ ].anchor | string | optional | Allows you to position a signature field on a PDF anchor. Pass the anchor name as the value. If no x and y parameters are passed, the field upper left corner will be positioned on the anchor lower left corner. Set only if field type is signature. |
| documents[ ].fields[ ].page | int | optional | The page number on which you want to position the field. Note that if you passed the anchor parameter and if you pass a page number, the system will look for the anchor value in this page only. Note that the page number is required if field type is dropdown. |
| documents[ ].fields[ ].x | int | optional | The field horizontal coordinate on the document page (in pixels). If you passed the anchor parameter, the system calculates the x coordinate in relation to the found anchor value. Note that the x argument is required if field type is dropdown. |
| documents[ ].fields[ ].y | int | optional | The field vertical coordinate on the document page (in pixels). If you passed the anchor parameter, the system calculates the y coordinate in relation to the found anchor value. Note that the y argument is required if field type is dropdown. |
| documents[ ].fields[ ].height | int | optional | The height of the field (expressed in PDF's default user space units). Set only if field type is text, label or dropdown. If not provided, the height is set to font height. Default value is 19. |
| documents[ ].fields[ ].width | int | optional | The width of the field (expressed in PDF's default user space units). Set only if field type is text, label or dropdown. Default value is 200. |
| documents[ ].fields[ ].tooltip | string | optional | Tooltips about the text the participant needs to add to the document during signature process. Set only if field type is text. Max 100 characters. |
| documents[ ].fields[ ].value | string | optional | Set only if field type is label or dropdown. If field type is label, it is the text you want to display in the label field. If field type is dropdown, it is the value of the dropdown option that will be selected by default for the dropdown list. If set, the value cannot be left empty and must not exceed 200 characters. The option value must not contain a backslash \. |
| documents[ ].fields[ ].font_size | number | optional | The font size of the field content. Possible values between 7 and 12. Default value is 12. Set only if field type is label. |
| documents[ ].fields[ ].minimum_required | int | optional | The minimum number of checkboxes to be checked by the participant. Default value is 0. Set only if field type is checkbox_group. |
| documents[ ].fields[ ].checked | boolean | optional | Set to true if you want the checkbox field or the radio button to be already checked. Default value is false. Set only if field type is checkbox or radiobutton. For more details, refer to Add checkbox fields or Add radio button fields. |
| documents[ ].fields[ ].parent | number | required | The temporary ID or the unique name of the parent checkbox group or radio button group to which the checkbox/radio button is linked. Set only if field type is checkbox or radiobutton. For more details, refer to Add checkbox fields or Add radio button fields. |
| documents[ ].fields[ ].required | boolean | optional | Whether the participant must choose an option or not. Set only if field type is dropdown. Default value is true. |
| documents[ ].fields[ ].options[*] | string | optional | To add a dropdown option, you must specify it as a key-value pair. The value of the options key must be appended to the options field between brackets (for example options[key]), and must not exceed 20 characters. The option key-value pair must be unique within the same dropdown list and the value must not exceed 200 characters. You can add up to 15 options per dropdown list. Note that the options value cannot be left empty and must not contain a backslash \. |
| documents[ ].initials_fields[ ].y | int | optional | The field vertical coordinate on the document pages (expressed in the PDF’s default user space units). The origin point is the bottom left hand corner of the displayed page (i.e the PDF's cropbox). |
| documents[ ].initials_fields[ ].alignment | string | optional | The alignment of the initials fields content. Possible values are left, center or right. Default value is right. |
| documents[ ].fields[ ].consents | array of strings | optional | Mandatory consents to agree to when signing the document. Mandatory consents associated with different fields for a same participant within a same document will be grouped on the signature page. Set only if field type is signature or visa. |
| documents[ ].fields[ ].optional_consents | array of strings | optional | Optional consents to agree to when signing the document. Optional consents associated with different fields for a same participant within a same document will be grouped on the signature page. Set only if field type is signature or visa. The feature needs to be activated on your workspace. |
| participants | array of objects | required | The participants of the transaction. |
| participants[ ].email | string | required | The participant's email. |
| participants[ ].designation | string | optional | The designation of the unknown participant. Max 250 characters. |
| participants[ ].description | string | optional | The description of the unknown participant. Max 250 characters. |
| participants[ ].invitation_subject | string | optional | The subject of the email invitation. |
| participants[ ].invitation_message | string | optional | The invitation message displayed in the email body. We support text format or xml with authorized xhtml tags only. For more details, refer to add invitation message. |
| participants[ ].invitation_redirect_url | string | optional | The redirect URL to be added to the link of invitation and reminder emails. |
| participants[ ].reminder_subject | string | optional | The subject of the email reminder. |
| participants[ ].reminder_message | string | optional | The reminder message displayed in the email body. We support text format or xml with authorized xhtml tags only. For more details, refer to set automatic reminders. |
| participants[ ].signed_documents_subject | string | optional | The subject of the email sent to the participant when signed documents are available. Max 100 characters. |
| participants[ ].signed_documents_message | string | optional | The message sent to the participant when signed documents are available. Max 1000 characters. We support text format or xml with authorized xhtml tags only. |
| participants[ ].min_signature_level | string | optional | The minimum required level of signature for a participant. Possible values are level0 (simple signature without authentication), level1 (simple signature), level2 (advanced signature), level3(advanced signature with qualified certificate) and level4 (qualified signature). Default value is level1. Note that the level0, level2, level3 and level4 signatures depend on your workspace entitlements. |
| participants[ ].name_constraint | string | optional | The full name of the participant as it must display in the signature. By passing this parameter, you do not authorize the participant to modify his/her full name, or to sign with a certificate if the full name in the certificate does not match the value you set. Do not pass this parameter if you pass the fullname_suggestion. (Deprecated) See full_name and full_name_type. |
| participants[ ].fullname_prerequisite | string | optional | The full name of the participant as it must display in the signature. By passing this parameter, you do not authorize the participant to modify his/her full name, or to sign with a certificate if the full name in the certificate does not match the value you set. Do not pass this parameter if you pass the fullname_suggestion. (Deprecated) See full_name and full_name_type. |
| participants[ ].fullname_suggestion | string | optional | The participant full name that you suggest for the transaction. If you pass this parameter, the participant will be able to edit his/her name on the signature or review page. Do not pass this parameter if you pass the fullname_prerequisite. (Deprecated) See full_name and full_name_type. |
| participants[ ].full_name | string | optional | The participant full name as it will display in the signature. |
| participants[ ].full_name_type | string | optional | The participant's full name type. Accepted values are suggestion (if you allow the participant to edit his/her name of the signature or review page) or prerequisite (if you don't allow the participant to edit his/her name on the signature or review page). Default value is suggestion. |
| participants[ ].request_full_name | boolean | optional | Set to true if you want the editor to fill the unknown participant full name. |
| participants[ ].phone_number_flex_constraint | string | optional | The participant mobile number that must be used for authentication. If you pass this parameter, the participant will not be able to modify the value you set, only if the minimum signature level requested is level1. However, if you requested a signature with a certificate, and if the participant already owns a certificate linked to a different mobile number, you authorize the participant to authenticate with the mobile number linked to his/her certificate. Do not pass this parameter if you pass the phone_number_suggestion. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number_flex_prerequisite | string | optional | The participant mobile number that must be used for authentication. If you pass this parameter, the participant will not be able to modify the value you set, only if the minimum signature level requested is level1. However, if you requested a signature with a certificate, and if the participant already owns a certificate linked to a different mobile number, you authorize the participant to authenticate with the mobile number linked to his/her certificate. Do not pass this parameter if you pass the phone_number_suggestion. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number_suggestion | string | optional | The participant mobile number that you suggest for authentication. If you pass this parameter, the participant will be able to modify the value you set. If the participant owns a certificate linked to a different mobile number, you authorize the participant to authenticate with the mobile number linked to his/her certificate. Do not pass this parameter if you pass the phone_number_flex_prerequisite. (Deprecated) See phone_number and phone_number_type. |
| participants[ ].phone_number | string | optional | The participant mobile number that is used for authentication. Expected format is E.164 ([+][country code][phone number including area code]). |
| participants[ ].phone_number_type | string | optional | The participant's mobile number type. Accepted values are suggestion (if you allow the participant to edit his/her phone number), flex_prerequisite (if you allow the participant to edit his/her phone number for advanced signature only), or prerequisite (if you never allow the participant to edit his/her phone number). Default value is suggestion. |
| participants[ ].request_phone_number | boolean | optional | Set to true if you want the editor to fill the unknown participant phone number. |
| participants[ ].schedule | array of int | optional | The emailing program of the participant. First value indicates how many hours after the participant action is open the system must send the invitation email. Next values indicate how many hours after the invitation email the system must send the reminder emails. Example 0, 48, 72 means that the invitation email must be sent 0 hours after the participant action is open, and that a reminder must be sent 48 hours and 72 hours after the initial invitation. Note that there must be a minimum of 24 hours between each sending. If you do not do not pass a schedule, no email will be sent to the participant. |
| participants[ ].do_not_invite_before | date | optional | The date and time after which the invitation is sent to the participant (after his action is opened). Set this parameter if you want to send a deferred invitation to your participant. Expected input format is ISO 8601 (ex: 2024-03-30T23:00:00Z). |
| participants[ ].stall_trigger | string | optional | Expressed in hours after the participant action is open, this value specifies the allotted time for the participant to perform the action. Beyond this delay, the participant will be flagged as stalled. |
| participants[ ].waiting_period | number | optional | The reflection period the participant has to respect before s/he can sign his/her documents. Cuurently, we only support this parameter with level1 signatures. |
| participants[ ].prevalidation_id | string | optional | The participant identity validation ID. We only support this parameter with level2 signatures and above. |
| participants[ ].signature_image | string | optional | The custom signature image that will be displayed on the signature cartridge. Expected input format is base64. Set only if min_signature_level is level2. The feature needs to be activated on your workspace. |
| sealers | array | optional | The list of sealers. |
| signatures | array of objects | required | The list of signature instructions. |
| signatures[ ].signer | string | required | The participant's email address, designation (is case the participant is unknown) or the moral person's certificate ID you want to assign to the field. |
| signatures[ ].field | string | required | The field that bears the signature or visa task. |
| captures | array of objects | optional | The list of documents that must be provided by participants within the signature process. |
| captures[ ].actor | string | required | The email of the participant who must provide the documents. |
| captures[ ].document_type | string | required | The type of document that is requested, among identity_document, iban, address_proof, tax_statement and other. |
| captures[ ].accepted_identity_documents | array of strings | optional | If the document_type is identity_document, this is the list of accepted identity documents. At least one of identity_card, passport, driving_licence or residence_permit. By default, all values are accepted. |
| captures[ ].total_items_required | int | optional | If you pass accepted_identity_documents, this is the total number of identity documents that are expected to be provided by the participant, among the list of accepted_identity_documents. Default value is 1. |
| captures[ ].covered_period | int | optional | If document_type is tax_statement, this is the covered period you want the participant to provide. 1 for last year, 2 for last two years, 3 for last three years, 4 for last four year and 5 for last five years. Default value is 2. |
| captures[ ].name | string | required | If the document_type is other, this is the name of the document you want the participant to provide, defined on your side. |
| captures[ ].tag | string | optional | If you request the same document_type value more than once for the same actor, you must pass a tag of your choice to differenciate each request. Otherwise, your request will overwrite the previous one. |
| captures[ ].guideline | string | optional | Any additional information you want to give to the participant in a limit of 100 characters. |
| reviews | array of objects | optional | The list of review instructions. |
| reviews[ ].reviewer | string | required | The reviewer's email address. |
| reviews[ ].recipient | string | required | The email address of the participant for whom the review is intended. |
| editions | array | optional | Instructions linked to editions. |
| editions[ ].editor | string | optional | The editor's email address. |
| editions[ ].recipient | string | optional | The reference of the unknown participant to be edited. |
| sequencing | array of objects | optional | The order of action between participants. |
| sequencing[ ].before | array of strings | required | The participants (identified by their email) or seals (identified by their ID) that you want to position before the participants or seals specified in the after array. |
| sequencing[ ].after | array of strings | required | The participants (identified by their email) or seals (identified by their ID) that you want to position after the participants or seals specified in the before array. |
| uploads | array | optional | If you requested a capture, the list of documents uploaded by the participant. |
| uploads[ ].actor | string | optional | The actor of the captured document. |
| uploads[ ].captured_documents | array | optional | Information about the captured documents. |
| uploads[ ].captured_documents[ ].id | string | optional | The captured document id. |
| uploads[ ].captured_documents[ ].document_type | string | optional | The type of the captured document. |
| uploads[ ].captured_documents[ ].captured_at | string | optional | The capture date. |
| uploads[ ].captured_documents[ ].name | string | optional | The name of the captured document. |
| uploads[ ].captured_documents[ ].tag | string | optional | The tag of the captured document. |
| uploads[ ].captured_documents[ ].tax_year | number | optional | The captured document's tax year(s). |
| uploads[ ].captured_documents[ ].accepted_identity_documents | array | optional | The capture’s accepted identity documents. |
| collected | array | optional | The list of done actions related to consents. |
| collected[ ].actor | string | optional | The email address of the actor who performed the consent action. |
| collected[ ].documents | array | optional | The list of documents involved in the consent action. |
| collected[ ].documents[ ].id | string | optional | The document's id. |
| collected[ ].documents[ ].granted_consents | array | optional | The agreed consents of the signature fields in this document. |
| collected[ ].documents[ ].ungranted_consents | array | optional | The non-agreed consents of the signature fields in this document. |
Returns
Response example
{
"object" : "transaction",
"id" : "tx_JdQ6za5LDmrL",
"folder_id" : "fol_DGX2qbq6yGmm",
"created_at" : "2024-04-16T14:39:17Z",
"started_at" : "2024-04-16T14:39:17Z",
"expires_at" : "2024-04-27T08:59:17Z",
"name" : "My full transaction request",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "TestAPI"
},
"state" : "started",
"participants" : [ {
"email" : "signer2@mail.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "reviewer1@mail.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"waiting_period" : 0,
"full_name_type" : "suggestion"
}, {
"email" : "signer@domain.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level2",
"invitation_subject" : "This is an invitation subject",
"invitation_message" : "This is an invitation message",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"name_constraint" : "Jane Doe",
"fullname_prerequisite" : "Jane Doe",
"full_name" : "Jane Doe",
"waiting_period" : 0,
"signature_image_reference" : "file_a9Vz28M28vDB3i2PDPoeK503E",
"full_name_type" : "prerequisite"
}, {
"email" : "reviewer2@mail.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ 0 ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"waiting_period" : 0,
"full_name_type" : "suggestion"
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_PzgJ",
"name" : "MyDoc",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_o7eo",
"name" : "text field",
"position" : {
"page" : 1,
"x" : 175,
"y" : 200,
"width" : 200,
"height" : 50
},
"built_in" : false,
"updatable" : true,
"deletable" : false,
"max_length" : 27,
"tooltip" : "Please enter your ID card number here!",
"required" : true,
"font_size" : 12,
"type" : "text"
}, {
"id" : "fld_K57",
"position" : {
"page" : 1,
"x" : 0,
"y" : 15,
"width" : 595,
"height" : 19
},
"type" : "initials",
"built_in" : false,
"updatable" : true,
"deletable" : true,
"font_size" : 12,
"alignment" : "center"
}, {
"id" : "fld_a946",
"name" : "signature field",
"position" : {
"page" : 1,
"x" : 150,
"y" : 275,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ "I hereby accept the terms and conditions stated in this document!" ],
"optional_consents" : [ "I accept to fill a satisfaction form once the signature process is completed!" ],
"updatable" : true,
"deletable" : false
} ]
} ],
"instructions" : {
"signatures" : [ {
"signer" : "signer@domain.com",
"field" : "fld_a946"
}, {
"signer" : "signer2@mail.com",
"field" : "fld_o7eo"
} ],
"reviews" : [ {
"reviewer" : "reviewer1@mail.com",
"recipient" : "signer@domain.com"
}, {
"reviewer" : "reviewer2@mail.com",
"recipient" : "signer2@mail.com"
} ],
"captures" : [ ],
"sequencing" : [ {
"before" : "signer@domain.com",
"after" : "signer2@mail.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_bw9x8G25Oe41d",
"actor" : "reviewer1@mail.com",
"state" : "open",
"url" : "https://apps.trunk.universign.net/npds/act_bw9x8G25Oe41d",
"tasks" : [ {
"type" : "review",
"state" : "todo",
"recipient" : "signer@domain.com",
"document" : "doc_PzgJ"
} ],
"stalled" : false
}, {
"id" : "act_WGZ00G4YKGBoX",
"actor" : "signer@domain.com",
"state" : "waiting",
"url" : "https://apps.trunk.universign.net/npds/act_WGZ00G4YKGBoX",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_a946"
} ],
"stalled" : false
}, {
"id" : "act_2ZdbYylnXrK1M",
"actor" : "signer2@mail.com",
"state" : "waiting",
"url" : "https://apps.trunk.universign.net/npds/act_2ZdbYylnXrK1M",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_o7eo"
} ],
"stalled" : false
} ],
"metadata" : {
"siren" : "123456"
},
"progress_value" : 0,
"ongoing_conversation" : false,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ "CC1@mail.com" ],
"carbon_copy_subject" : "This is a CC notification subject",
"carbon_copy_message" : "This is a CC notification message",
"collected" : [ ],
"max_expiry" : "180_days",
"uploads" : [ ],
"issuing_entity" : {
"id" : "iss_aX0wDPD86DlQ",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
The API returns a transaction object in draft state if you set the autostart parameter to false, or in started state if you set it to true.
The internal IDs you passed in the request are replaced with Universign IDs.
Signed documents
Retrieve a signed document
GET /v1/transactions/{transaction_id}/archive/documents/{document_id}/download
GET v1/archives/{transaction_id}/documents/{document_id}/download
To download a signed document, you must pass the ID of the signed document in the path parameters as shown in the request examples. You must send one request per signed document to download.
There are two ways to download a captured document:
via the
/transactionsendpoint
If you need to download a signed document once the transaction is completed, or within 60 days after the transaction is completed (see request example 1).via the
/archivesendpoint
If you need to download a signed document at any time, once the transaction is archived (see request example 2).
Request example 1
curl https://api.universign.com/v1/transactions/tx_YxwdbnAdl9vO/archive/documents/doc_87oO/download
Request example 2
curl https://api.universign.com/v1/archives/tx_YxwdbnAdl9vO/documents/doc_87oO/download
Returns
The API returns the signed document in PDF.
Captured documents
Captured documents endpoints
POST /v1/transactions/{transaction_id}/captures/{document_type}
GET v1/transactions/{transaction_id}/captured-documents/{cdoc_id}/download
GET /v1/archives/{transaction_id}/captured-documents/{cdoc_id}/download
Add a capture instruction to a transaction
POST /v1/transactions/{transaction_id}/captures/{document_type}
This endpoint enables you to add a capture instruction to a transaction. You must send one request per capture instruction. To remove a capture instruction from a transaction, simply pass a delete parameter in your request.
Request examples
To capture 2 identity documents
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/captures/identity_document \
-d actor=jane@universign.com \
-d accepted_identity_documents=identity_card \
-d accepted_identity_documents=passport \
-d total_items_required=2 \
-d guideline=Black and white scans are not allowed!
To capture 2 iban
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/captures/iban \
-d actor=jane@universign.com \
-d tag=personal \
-d guideline=please provide your iban!
and
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/captures/iban \
-d actor=jane@universign.com \
-d tag=spouse \
-d guideline=please provide spouse iban!
To capture an address proof
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/captures/address_proof \
-d actor=jane@universign.com \
-d guideline=document must not be older than 3 months!
To capture a tax statement
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/captures/tax_statement \
-d actor=jane@universign.com \
-d covered_period=3
To capture other document types
curl https://api.universign.com/v1/transactions/tx_wnqKgxAnVgmy/captures/other \
-d actor=jane@universign.com \
-d tag=vitale \
-d name=carte_vitale
| Arguments | Type | Description | |
|---|---|---|---|
| actor | string | required | The email of the participant who must provide documents. |
| document_type | string | required | The type of document that is requested, among identity_document, iban, address_proof tax_statement and other. |
| accepted_identity_documents | array of strings | optional | If the document_type is identity_document, the list of accepted identity documents. At least one of identity_card, passport, driving_licence or residence_permit. By default, all values are accepted. |
| total_items_required | int | optional | If you pass accepted_identity_documents, this is the total number of identity documents that are expected to be provided by the participant, among the list of accepted_identity_documents. Default value is 1. |
| covered_period | int | optional | If document_type is tax_statement, this is the covered period you want the participant to provide. 1 for last year, 2 for last two years, 3 for last three years, 4 for last four year and 5 for last five years. Default value is 2. |
| name | string | required | If the document_type is other, this is the name of the document you want the participant to provide, defined on your side. |
| tag | string | optional | If you request the same document_type value more than once for the same actor, you must pass a tag of your choice to differenciate each request. Otherwise, your request will overwrite the previous one. |
| guideline | string | optional | Any additional information you want to give to the participant in a limit of 100 characters. |
| delete | boolean | optional | Set to true to delete the capture instruction. |
Returns
The API returns a transaction object, updated with a new capture instruction in the instructions sub-object and a new task in the actions array, as shown in the code example.
Response example
{
"object" : "transaction",
"id" : "tx_wnqKgxAnVgmy",
"folder_id" : "fol_JxmJlV5P922X",
"created_at" : "2024-10-08T08:22:48Z",
"duration" : 4320,
"name" : "NewName",
"folder_name" : "Default folder",
"stalled" : false,
"language" : "en",
"creator" : {
"workspace_name" : "DemoWS",
"api_key_name" : "ApiRefKey"
},
"state" : "draft",
"participants" : [ {
"email" : "John@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jean@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "$Designation",
"phone_number_type" : "suggestion",
"request_phone_number" : false,
"min_signature_level" : "level1",
"schedule" : [ ],
"ongoing_conversation" : false,
"has_unread_message" : false,
"state" : "completed",
"request_full_name" : false,
"full_name_type" : "suggestion",
"waiting_period" : 0
}, {
"email" : "jane@universign.com",
"phone_number_type" : "suggestion",
"min_signature_level" : "level1",
"invitation_message" : "SampleMessage",
"schedule" : [ ],
"ongoing_conversation" : true,
"has_unread_message" : false,
"state" : "open",
"full_name_type" : "suggestion",
"waiting_period" : 7
} ],
"watchers" : [ ],
"sealers" : [ ],
"documents" : [ {
"id" : "doc_6AVL",
"name" : "DocName",
"editable" : true,
"updatable" : true,
"deletable" : false,
"fields" : [ {
"id" : "fld_VoDl",
"name" : "myField",
"position" : {
"page" : 1,
"x" : 325,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_6V4P",
"name" : "customerField",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 50
},
"type" : "signature",
"built_in" : false,
"consents" : [ ],
"optional_consents" : [ ],
"updatable" : true,
"deletable" : false
}, {
"id" : "fld_KYPA",
"name" : "TextField",
"type" : "text",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"tooltip" : "Please",
"required" : true,
"font_size" : 12
}, {
"id" : "fld_4Md4",
"name" : "LabelField",
"type" : "label",
"position" : {
"page" : 1,
"x" : 75,
"y" : 200,
"width" : 24,
"height" : 16
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"value" : "This",
"font_size" : 10
} ],
"big_file" : false,
"available" : true
} ],
"instructions" : {
"signatures" : [ {
"signer" : "jane@universign.com",
"field" : "fld_6V4P"
}, {
"signer" : "jean@universign.com",
"field" : "fld_VoDl"
} ],
"reviews" : [ ],
"captures" : [ {
"actor" : "jane@universign.com",
"document_type" : "identity_document",
"accepted_identity_documents" : [ "passport", "identity_card" ],
"total_items_required" : 2,
"guideline" : "Black"
} ],
"sequencing" : [ {
"before" : "jane@universign.com",
"after" : "jean@universign.com"
} ],
"editions" : [ ]
},
"actions" : [ {
"id" : "act_A8BqrxkM51bDz",
"actor" : "jane@universign.com",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_A8BqrxkM51bDz",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_6V4P"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
}, {
"type" : "capture",
"state" : "todo",
"document_type" : "identity_document"
} ],
"stalled" : false
}, {
"id" : "act_aJVb9ny223kPo",
"actor" : "jean@universign.com",
"state" : "waiting",
"url" : "https://apps.universign.com/npds/act_aJVb9ny223kPo",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_VoDl"
} ],
"stalled" : false
} ],
"metadata" : { },
"progress_value" : 0,
"ongoing_conversation" : true,
"has_unread_message" : false,
"origin" : "API",
"carbon_copies" : [ ],
"collected" : [ ],
"uploads" : [ ],
"max_expiry" : "180_days",
"issuing_entity" : {
"id" : "iss_xa1LoEebXQM3",
"name" : "DemoWS",
"lock_sender_name_display" : false
},
"private" : false
}
Retrieve a captured document ID
Once a participant has provided the requested documents, the transaction object is updated with an uploads array as shown in the code example. The uploads array contains an ID for each document captured. You need this ID to be able to download the captured document.
Response example
{
"object" : "transaction",
"id" : "tx_aA5g6yzYVYW8",
"folder_id" : "fol_kOxlKmLbOdz7",
"metadata": {
"siren": "123456"
},
"name" : "My transaction",
"language" : "en",
"duration": 15500,
"documents" : [{
"file_id" : "file_Wq0eZlYWz6AKZSbezwb5nGv1rD",
"name" : "my_document_name",
"id" : "my_internal_id",
"fields" : [
{
"id" : "field_id_1",
"name" : "field1",
"page" : 1,
"x" : 0,
"y" : 0
},{
"id" : "field_id_2",
"name" : "field2",
"page" : 1,
"x" : 0,
"y" : 0
}]
} ],
"signatures" : [ {
"field" : "field_id_1",
"signer" : "signer@domain.com"
}, {
"field" : "field_id_2",
"signer" : "signer2@mail.com"
} ],
"reviews" : [ {
"recipient" : [ "signer@domain.com" ],
"reviewer" : "reviewer1@mail.com"
}, {
"recipient" : [ "signer2@mail.com" ],
"reviewer" : "reviewer2@mail.com"
} ],
"sequencing" : [
{
"before" : ["signer@domain.com"],
"after": ["signer2@mail.com"]
}],
"captures" : [
{
"actor" : "signer@domain.com",
"document_type" : "identity_document",
"accepted_identity_documents" : ["identity_card", "passport"],
"total_items_required" : "2",
"guideline" : "the document must be in color"
},{
"actor" : "signer@domain.com",
"document_type" : "iban",
"tag" : "personal",
"guideline" : "please provide your iban"
},{
"actor" : "signer@domain.com",
"document_type" : "iban",
"tag" : "spouse",
"guideline" : "please provide spouse iban"
} ],
"participants" : [
{
"email" : "signer@domain.com",
"schedule" : [0],
"name_constraint" : "Jane Doe",
"fullname_prerequisite" : "Jane Doe",
"invitation_subject" : "This is an invitation subject",
"invitation_message" : "This is an invitation message"
},{
"email" : "signer2@mail.com",
"schedule" : [0]
},{
"email" : "reviewer1@mail.com",
"schedule" : [0]
},{
"email" : "reviewer2@mail.com",
"schedule" : [0]
}],
"carbon_copies" : [ ],
"uploads": [
{
"actor": "signer@domain.com",
"captured_documents": [
{
"id": "cdoc_dQr7AaAQXmXZ0",
"document_type": "identity_document",
"captured_at": "2022-07-07T17:08:30Z"
},
{
"id": "cdoc_DOlbJMK8GxBr",
"document_type": "identity_document",
"captured_at": "2022-07-07T17:08:30Z"
},
{
"id": "cdoc_Lb85ew1Dybk2Z",
"document_type": "iban",
"tag": "personal",
"captured_at": "2022-07-07T17:08:30Z"
},
{
"id": "cdoc_okOQMJng82lOy",
"document_type": "iban",
"tag": "spouse",
"captured_at": "2022-07-07T17:08:30Z"
}
]
}
]
}
Download a captured document
GET v1/transactions/{transaction_id}/captured-documents/{cdoc_id}/download
GET /v1/archives/{transaction_id}/captured-documents/{cdoc_id}/download
To download a captured document, you must pass the ID of the captured document in the path parameters as shown in the request examples. You must send one request per captured document to download.
There are two ways to download a captured document:
via the
/transactionsendpoint
If you need to download a document uploaded by a participant before the transaction is completed for example, or within 60 days after the transaction is completed (see request example 1).via the
/archivesendpoint
If you need to download a captured document at any time, once the transaction is archived (see request example 2).
Request example 1
curl https://api.universign.com/v1/transactions/tx_YxwdbnAdl9vO/captured-documents/cdoc_87oO/download
Request example 2
curl https://api.universign.com/v1/archives/tx_YxwdbnAdl9vO/captured-documents/cdoc_O1/download
Returns
The API returns the captured document in PDF.
Consumption report
Retrieve consumption report
This endpoint enables you to compute and retrieve your transaction events report. It allows you to figure out the signatures, visas, seals and reviews performed over a given period.
Request example
curl https://api.universign.com/v1/events/report?created_gt=2022-12-19T08:55:17.983Z&created_lt=2023-01-19T00:00:00Z
| Arguments | Type | Description | |
|---|---|---|---|
| created_gt | date | required | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns report on events that occurred at and after the specified date. |
| created_lt | date | optional | Expected value is an ISO 8601-compliant date, with or without milliseconds (ex: 2021-09-09T08:55:17.983Z or 2021-09-09T08:55Z ). Returns report on events that occurred before the specified date. |
Returns
The API returns an events-report object, as in the description below:
Response example
{
"object":"events-report",
"tenant_id":"wsp_DG0m94dlrOwd",
"started_transactions":760,
"visas":24,
"read_documents":24,
"seals":111,
"sealed_documents":99,
"reviews":74,
"captures":65,
"signatures":271,
"signed_documents":266,
"signatures_by_required_level": {
"level_0": 3,
"level_1": 222,
"level_2": 46
},
"signed_documents_by_required_level": {
"level_0": 3,
"level_1": 217,
"level_2": 46
}
}
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is events_report. |
| tenant_id | string | The tenant's id. |
| started_transactions | number | The total number of started transactions over the period. |
| visas | number | The number of visas performed over the period. |
| read_documents | number | The number of documents read over the period. |
| seals | number | The number of seals used over the period. |
| sealed_documents | number | The number of sealed documents over the period. |
| reviews | number | The number of reviews used over the period. |
| captures | number | The number of documents captured over the period. |
| signatures | number | The number of signatures used over the period. |
| signatures_by_required_level | object | The breakdown of signatures by required level over the period. |
| signartures_by_required_level[ ].level_0 | number | The number of required level0 signatures. |
| signartures_by_required_level[ ].level_1 | number | The number of required level1 signatures. |
| signartures_by_required_level[ ].level_2 | number | The number of required level2 signatures. |
| signartures_by_required_level[ ].level_3 | number | The number of required level3 signatures. |
| signed_documents_by_required_level | object | The breakdown of documents signed by required level over the period. |
| signed_documents_by_required_level[ ].level_0 | number | The number of documents signed by level0 signatures. |
| signed_documents_by_required_level[ ].level_1 | number | The number of documents signed by level1 signatures. |
| signed_documents_by_required_level[ ].level_2 | number | The number of documents signed by level2 signatures. |
| signed_documents_by_required_level[ ].level_3 | number | The number of documents signed by level3 signatures. |
| signed_documents_by_required_level[ ].level_4 | number | The number of documents signed by level4 signatures. |
Issuing entities
Issuing entity endpoints
POST /v1/issuing-entities
POST /v1/issuing-entities/{id}
GET /v1/issuing-entities/{id}
POST /v1/issuing-entities/{id}/activate
POST /v1/issuing-entities/{id}/deactivate
POST /v1/issuing-entities/{id}/retire
GET /v1/issuing-entities
The issuing entities object
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is issuing_entity. |
| id | string | The ID of the issuing entity. |
| workspace_entity | boolean | Indicates whether the issuing entity is the workspace initial issuing entity. |
| name | string | The name of the issuing entity. |
| sender_name_display | string | The sender name display of the issuing entity. |
| lock_sender_name_display | boolean | Indicates whether the sender name display option is locked. |
| default | boolean | Indicates whether the issuing entity is used by default. |
| active | boolean | Indicated whether the issuing entity is active or deactive. |
| sealer_logo_display | string | The sealer logo that will display on the document. Accepted values are certificate (Universign logo), issuing_entity (issuing entity logo), none (no logo to display). |
| pds_configuration | array | The signature page configuration information. |
| pds_configuration[ ].header_background_color | string | The header background color to be displayed on the signature page. |
| pds_configuration[ ].header_text_color | string | The header text color to be displayed on the signature page. |
| pds_configuration[ ].header_steps_color | string | The steps color to be displayed on the signature page. |
| pds_configuration[ ].body_background_color | string | The body background color to be displayed on the signature page. |
| pds_configuration[ ].body_text_color | string | The body text color to be displayed on the signature page. |
| pds_configuration[ ].body_button_background_color | string | The button color to be displayed on the signature page. |
| pds_configuration[ ].body_button_text_color | string | The button text color to be displayed on the signature page. |
| pds_configuration[ ].body_button_border_radius | number | The button border radius to be displayed on the signature page. |
| pds_configuration[ ].body_links_color | string | The links color to be displayed on the signature page. |
| pds_configuration[ ].body_underlined_links | boolean | Indicates whether the links to be displayed on the signature page will be underlined. |
| sms_configuration | array | Information about the entity's sms customization. |
| sms_configuration[ ].entity_short_name | string | The entity short name that will display in the customized sms. |
Create an issuing entity
This endpoint enables you to create an issuing entity. You can create a maximum of 20 issuing entities per workspace.
Request example
curl https://api.universign.com/v1/issuing-entities
\
-d name=MyNewEntity
\
-d sender_name_display=name_issuing_entity
-F logo=@entity_logo
\
-d sealer_logo_display=certificate
\
-d sms_short_name=MysmsShortName
\
-d header_background_color=#FFFFFF
\
-d header_text_color=#3B4F63
\
-d header_steps_color=#0072AF
\
-d body_background_color=#FFFFFF
\
-d body_text_color=#3B4F63
\
-d body_button_background_color=#0072AF
\
-d body_button_text_color=#FFFFFF"
\
-d body_button_border_radius=24
\
-d body_links_color=#0072AF
\
-d body_underlined_links=false
| Arguments | Type | Description | |
|---|---|---|---|
| name | string | required | The name of the issuing entity. |
| is_default | boolean | optional | Set to true, if you want the issuing entity to be used by default. |
| sender_name_display | string | optional | In whose name the transaction is sent. Either issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). Default value is name_email. |
| lock_sender_name_display | boolean | optional | Set to true to lock the sender_name_display option. |
| logo | file | optional | The logo of the issuing entity. If no logo is set, the workspace logo is used. Accepted formats are JPEG and PNG with a maximum size limit of 2MB. |
| sealer_logo_display | string | optional | The sealer logo that will display on the document. Accepted values are certificate (Universign logo), issuing_entity (issuing entity logo), none (no logo to display). Default value is certificate. |
| sms_short_name | string | optional | The entity short name you want to display in the customized sms (max 20 characters). Value must not be empty. |
| header_background_color | string | optional | The header background color to be displayed on the signature page. |
| header_text_color | string | optional | The header text color to be displayed on the signature page. |
| header_steps_color | string | optional | The steps color to be displayed on the signature page. |
| body_background_color | string | optional | The body background color to be displayed on the signature page. |
| body_text_color | string | optional | The body text color to be displayed on the signature page. |
| body_button_background_color | string | optional | The button color to be displayed on the signature page. |
| body_button_text_color | string | optional | The button text color to be displayed on the signature page. |
| body_button_border_radius | number | optional | The button border radius to be displayed on the signature page. |
| body_links_color | string | optional | The links color to be displayed on the signature page. |
| body_underlined_links | boolean | optional | Set to true if you want the links on the signature page to be underlined. |
Returns
The API returns an issuing-entity object, as in the description below:
Response example
{
"object" : "issuing_entity",
"id" : "iss_3z",
"workspace_entity" : false,
"name" : "new_issuer",
"sender_name_display" : "name_issuing_entity",
"lock_sender_name_display" : false,
"default" : false,
"sealer_logo_display" : "certificate",
"sms_configuration" : {
"entity_short_name" : "MysmsShortName",
},
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : false
}
}
Update an issuing entity
This endpoint enables you to update an issuing entity.
Request example
curl https://api.universign.com/v1/issuing-entities/iss_3z
\
-d name=MyNewEntity
\
-d sender_name_display=name_issuing_entity
-F logo=@new_entity_logo
\
-d sealer_logo_display=issuing_entity
\
-d sms_short_name=NewsmsShortName
\
-d delete_sms_short_name=true
\
-d header_background_color=#FFFFFF
\
-d header_text_color=#3B4F63
\
-d header_steps_color=#0072AF
\
-d body_background_color=#FFFFFF
\
-d body_text_color=#3B4F63
\
-d body_button_background_color=#0072AF
\
-d body_button_text_color=#FFFFFF
\
-d body_button_border_radius=24
\
-d body_links_color=#0072AF
\
-d body_underlined_links=true
| Arguments | type | Description | |
|---|---|---|---|
| is_default | boolean | optional | Set to true, if you want the issuing entity to be used by default. |
| sender_name_display | string | optional | In whose name the transaction is sent. Either issuing_entity (the name of the issuing entity), name_issuing_entity (the name of the person and the name of the issuing entity), name_email_issuing_entity(the name and email of the person and the name of the issuing entity) or name_email (the name and email of the person who created the transaction). Default value is name_email. |
| logo | file | optional | The logo of the issuing entity. If no logo is set, the workspace logo is used. Accepted formats are JPEG and PNG with a maximum size limit of 2MB. |
| lock_sender_name_display | boolean | optional | Set to true to lock the sender_name_display option. |
| sealer_logo_display | string | optional | The sealer logo that will display on the document. Accepted values are certificate (Universign logo), issuing_entity (issuing entity logo), none (no logo to display). |
| sms_short_name | string | optional | The entity short name you want to display in the customized sms (max 20 characters). Value must not be empty. |
| delete_sms_short_name | boolean | optional | Set to true, if you don't want your sms to be customized. |
| header_background_color | string | optional | The header background color to be displayed on the signature page. |
| header_text_color | string | optional | The header text color to be displayed on the signature page. |
| header_steps_color | string | optional | The steps color to be displayed on the signature page. |
| body_background_color | string | optional | The body background color to be displayed on the signature page. |
| body_text_color | string | optional | The body text color to be displayed on the signature page. |
| body_button_background_color | string | optional | The button color to be displayed on the signature page. |
| body_button_text_color | string | optional | The button text color to be displayed on the signature page. |
| body_button_border_radius | number | optional | The button border radius to be displayed on the signature page. |
| body_links_color | string | optional | The links color to be displayed on the signature page. |
| body_underlined_links | boolean | optional | Set to true if you want the links on the signature page to be underlined. |
Returns
The API returns an issuing-entity object, updated with the values you entered as request parameters:
Response example
{
"object" : "issuing_entity",
"id" : "iss_3z",
"workspace_entity" : false,
"name" : "new_issuer",
"sender_name_display" : "name_email_issuing_entity",
"lock_sender_name_display" : true,
"default" : true,
"sealer_logo_display" : "issuing_entity",
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : true
}
}
Retrieve an issuing entity
This endpoint enables you to retrieve an issuing entity.
Request example
curl https://api.universign.com/v1/issuing-entities/iss_3z
Returns
The API returns an issuing-entity object, as it was last updated:
Response example
{
"object" : "issuing_entity",
"id" : "iss_3z",
"workspace_entity" : false,
"name" : "new_issuer",
"sender_name_display" : "name_email_issuing_entity",
"lock_sender_name_display" : true,
"default" : true,
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : false
}
}
Activate an issuing entity
This endpoint enables you to activate the workspace issuing entity.
Request example
curl https://api.universign.com/v1/issuing-entities/iss_5X/activate
Returns
The API returns an issuing-entity object.
Response example
{
"object" : "issuing_entity",
"id" : "iss_5X",
"workspace_entity" : true,
"name" : "workspace_issuer",
"sender_name_display" : "name_email_issuing_entity",
"lock_sender_name_display" : true,
"default" : false,
"active" : true,
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : false
}
}
Deactivate an issuing entity
This endpoint enables you to deactivate the workspace issuing entity.
Note that you cannot deactivate the workspace issuing entity if it is used by default or if no other issuing entities are available within your workspace.
Request example
curl https://api.universign.com/v1/issuing-entities/iss_5X/deactivate
Returns
The API returns an issuing-entity object.
Response example
{
"object" : "issuing_entity",
"id" : "iss_5X",
"workspace_entity" : true,
"name" : "workspace_issuer",
"sender_name_display" : "name_email_issuing_entity",
"lock_sender_name_display" : true,
"default" : false,
"active" : false,
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : false
}
}
Retire an issuing entity
This endpoint enables you to retire an issuing entity.
Note that you can retire neither the workspace issuing entity or any other issuing entity used by default.
Request example
curl https://api.universign.com/v1/issuing-entities/iss_3z/retire
Returns
A successful request returns an empty 200 response.
Response example
List issuing entities
This endpoint enables you to retrieve all issuing entities within your workspace.
Request example
curl https://api.universign.com/v1/issuing-entities?starting_after=iss_5X&size=5
| Arguments | Type | Description | |
|---|---|---|---|
| size | int | optional | The number of issuing entities you want to retrieve, starting from the workspace issuing entity. Maximum is 20. |
| name | string | optional | The name of issuing entity you want to retrieve. |
| ending_before | string | optional | Expected value is an issuing entity ID. Use for pagination to return the issuing entities listed before the specified one. Do not pass if you set the starting_after parameter. |
| starting_after | string | optional | Expected value is an issuing entity ID. Use for pagination to return the issuing entities listed after the specified one. Do not pass if you set the ending_before parameter. |
| only_active | boolean | optional | If set, returns only active issuing entities. |
| retired | boolean | optional | If set to true, returns only retired issuing entities. If set to false, the returned list will not include the retired issuing entities. If not set, the returned list will include retired issuing entities. |
Returns
The API returns the list of all issuing entities matching your request. The response description is as follows:
Response example
{
"has_more" : false,
"content" : [ {
"object" : "issuing_entity",
"id" : "iss_5X",
"workspace_entity" : true,
"name" : "workspace_issuer",
"sender_name_display" : "name_email_issuing_entity",
"lock_sender_name_display" : true,
"default" : false,
"active" : true,
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : false
}
}, {
"object" : "issuing_entity",
"id" : "iss_3z",
"workspace_entity" : false,
"name" : "new_issuer",
"sender_name_display" : "name_issuing_entity",
"lock_sender_name_display" : false,
"default" : false,
"pds_configuration" : {
"header_background_color" : "#FFFFFF",
"header_text_color" : "#3B4F63",
"header_steps_color" : "#0072AF",
"body_background_color" : "#FFFFFF",
"body_text_color" : "#3B4F63",
"body_button_background_color" : "#0072AF",
"body_button_text_color" : "#FFFFFF",
"body_button_border_radius" : 24,
"body_links_color" : "#0072AF",
"body_underlined_links" : false
}
} ]
}
| Parameters | Type | Description |
|---|---|---|
| has more | boolean | If there are more existing issuing entities in the workspace than the ones returned in the response. |
| content | string | The list of issuing entities. |
| content[ ].object | string | The object's type. Value is issuing-entity. |
| content[ ].id | string | The issuing entity ID. |
| content[ ].workspace_entity | boolean | Indicates whether the issuing entity is the workspace initial issuing entity. |
| content[ ].name | string | The name of the issuing entity. |
| content[ ].sender_name_display | string | The sender name display of the issuing entity. |
| content[ ].lock_sender_name_display | boolean | Indicates whether the sender name display option is locked. |
| content[ ].default | boolean | Indicates whether the issuing entity is used by default. |
| content[ ].active | boolean | Indicated whether the issuing entity is active or deactive. |
| content[ ].sealer_logo_display | string | optional |
| content[ ].pds_configuration.header_background_color | string | The header background color to be displayed on the signature page. |
| content[ ].pds_configuration.header_text_color | string | The header text color to be displayed on the signature page. |
| content[ ].pds_configuration.header_steps_color | string | The steps color to be displayed on the signature page. |
| content[ ].pds_configuration.body_background_color | string | The body background color to be displayed on the signature page. |
| content[ ].pds_configuration.body_text_color | string | The body text color to be displayed on the signature page. |
| content[ ].pds_configuration.body_button_background_color | string | The button color to be displayed on the signature page. |
| content[ ].pds_configuration.body_button_text_color | string | The button text color to be displayed on the signature page. |
| content[ ].pds_configuration.body_button_border_radius | number | The button border radius to be displayed on the signature page. |
| content[ ].pds_configuration.body_links_color | string | The links color to be displayed on the signature page. |
| content[ ].pds_configuration.body_underlined_links | boolean | Indicates whether the links to be displayed on the signature page will be underlined. |
| content[ ].sms_configuration.entity_short_name* | string | The entity short name that will display in the customized sms. |
| content[ ].retired* | boolean | Indicates whether the returned list will include only retired issuing entities. |
Identity prevalidation
Identity prevalidation endpoints
Prevalidating an identity document enables you to know if it is valid before and independently from a signature transaction.
Identity prevalidation is a two-step process during which data is extracted from the identity document and then matched with the data expected on your side. Both steps must be completed successfully to return a valid identity validation ID (to be used in the transaction).
An identity validation ID provides a guarantee that the electronic certificate associated with the identity document will be issued successfully and immediately, within a future signature transaction or a standalone operation.
Prevalidation object
| Parameters | Type | Description |
|---|---|---|
| object | string | The object's type. Value is id-validation. |
| id | string | The identity validation ID. |
| status | string | The identity prevalidation status. Possible values are success, extraction_failure or constraints_failure. |
| verification | object | The identity prevalidation verification result. |
| verification.successful_checks | array | The list of successful checks for the matching between data extracted from the identity document and the data expected. |
| verification.failed_checks | array | The list of failed checks for the matching between data extracted from the identity document and the data expected. |