cURL

API Reference

Base URLs:

https://api.universign.com (PROD)  
https://api.alpha.universign.com (PREPROD)

The Universign API is organized around REST. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses 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.

Run in Postman

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: level1 (simple signature), level2 (advanced signature). Default value is level1, level0 (simple signature without authentication).
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 Value is 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).
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[ ].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 The value of the field content. Displays only if field type is label.
documents[ ].fields[ ].alignment string The alignment of initial fields content. Displays only for initials-fields.
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 email 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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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" : [ ],
  "max_expiry" : "180_days",
  "uploads" : [ ],
  "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_a4zrqgPgMn94

Returns

The API returns transaction object, as it was last updated.

Response example

{
  "object" : "transaction",
  "id" : "tx_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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" : [ ],
  "max_expiry" : "180_days",
  "uploads" : [ ],
  "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_a4zrqgPgMn94 \
-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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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" : [ ],
  "max_expiry" : "180_days",
  "uploads" : [ ],
  "issuing_entity" : {
    "id" : "iss_xa1LoEebXQM3",
    "name" : "DemoWS",
    "lock_sender_name_display" : false
  },
  "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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "started_at" : "2024-03-25T15:01:41Z",
  "expires_at" : "2024-03-28T15:01:41Z",
  "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",
    "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_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ {
      "actor" : "jane@universign.com",
      "document_type" : "identity_document",
      "accepted_identity_documents" : [ "passport", "identity_card" ],
      "total_items_required" : 2,
      "guideline" : "'the"
    }, {
      "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_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    }, {
      "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_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "started_at" : "2024-03-25T15:01:41Z",
  "expires_at" : "2024-03-28T15:01:41Z",
  "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_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ {
      "actor" : "jane@universign.com",
      "document_type" : "identity_document",
      "accepted_identity_documents" : [ "passport", "identity_card" ],
      "total_items_required" : 2,
      "guideline" : "'the"
    }, {
      "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_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "started_at" : "2024-03-25T15:01:41Z",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    }, {
      "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_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "stalled" : false
  } ],
  "metadata" : { },
  "progress_value" : 0,
  "ongoing_conversation" : true,
  "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
}

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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "started_at" : "2024-03-25T15:01:41Z",
  "closed_at" : "2024-03-25T15:01:42Z",
  "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_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ {
      "actor" : "jane@universign.com",
      "document_type" : "identity_document",
      "accepted_identity_documents" : [ "passport", "identity_card" ],
      "total_items_required" : 2,
      "guideline" : "'the"
    }, {
      "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_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "started_at" : "2024-03-25T15:01:41Z",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    }, {
      "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_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "stalled" : false
  } ],
  "metadata" : { },
  "progress_value" : 0,
  "ongoing_conversation" : true,
  "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
}

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_a4zrqgPgMn94",
    "folder_id" : "fol_JxmJlV5P922X",
    "created_at" : "2024-03-25T14:59:21Z",
    "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_a4zrqgPgMn94/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
DELETE /v1/transactions/{transaction_id}/documents/{document_id}
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 wand to upload to Universign. Expected file format is PDF, and size must not exceed 25Mo.

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_a4zrqgPgMn94/documents \
-d document=file_GaKg9J4lokDQQTekzddAKol5mg \
-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_aDo",
  "name" : "DocName",
  "editable" : true,
  "updatable" : true,
  "deletable" : true,
  "fields" : [ ]
}

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_a4zrqgPgMn94/documents/doc_aDo \
-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_aDo",
  "name" : "DocName",
  "editable" : true,
  "updatable" : true,
  "deletable" : true,
  "fields" : [ ]
}

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_a4zrqgPgMn94/documents/doc_6ADe \
-X DELETE

Returns

A successful DELETE request on a transaction document 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 either a signature, visa, text or label field in the document and set a series of optional or required parameters, 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_a4zrqgPgMn94/documents/doc_aDo/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_a4zrqgPgMn94/documents/doc_aDo/fields \
-d name=myField

To create a visa field:

curl https://api.universign.com/v1/transactions/tx_a4zrqgPgMn94/documents/doc_aDo/fields \
-d name=agentField \
-d type=visa

To create a text field

curl https://api.universign.com/v1/transactions/tx_a4zrqgPgMn94/documents/doc_aDo/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_a4zrqgPgMn94/documents/doc_aDo/fields \
-d type=label \
-d name=LabelField \
-d page=1 \
-d x=75 \
-d y=200 \
-d value=This text is only for display! \
-d font_size=10
Arguments Type Description
name string optional The name of the field.
type string optional The type of the field. Possible values, signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you want to add an empty text field to be filled by the participant during the signature process), label (if you want to add a read only text on the document).
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.
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.
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.
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.
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 or label. If not provided, the height is set to font height.
width string optional The width of the field (expressed in PDF's default user space units). Set only if field type is text or label. 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 The text you want to display in the label field. Set only if field type is label.
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.

Returns

The API returns a field sub-object.

Response examples

For a signature field visible on the document:

{
  "id" : "fld_JX2n",
  "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_21xz",
  "name" : "myField",
  "type" : "signature",
  "built_in" : false,
  "consents" : [ ],
  "optional_consents" : [ ],
  "updatable" : true,
  "deletable" : true
}

For a visa field:

{
  "id" : "fld_Ogon",
  "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 is only for display!",
  "font_size" : 10,
  "type" : "label"
}
Parameters Type Description
id string The field ID.
name string The name of the field.
type string Value is signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you want to add an empty text field to be filled by the participant during the signature process), label (if you want to add a read only text on the document).
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.width int The field width (in pixels). Default value is 200.
position.height int The field height (in pixels). Default value is 50 .
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 The text you want to display in the label field. Displays only if field type is label.
alignment string The alignment of initial fields content. Displays only for initials-fields.

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 vlaue 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_a4zrqgPgMn94/documents/doc_aDo/fields/fld_21xz \
-d page=1 \
-d x=325 \
-d y=200

To make a visible field invisible:

curl https://api.universign.com/v1/transactions/tx_a4zrqgPgMn94/documents/doc_aDo/fields/fld_Ogon \
-d type=signature \
-d page=0

To turn a signature field into a visa field:

curl https://api.universign.com/v1/transactions/tx_a4zrqgPgMn94/documents/doc_aDo/fields/fld_Ogon \
-d type=visa
Arguments Type Description
name string optional The name of the field.
type string optional The type of the field. Possible values, signature (if the participant needs to sign the document), visa (if the participant only needs to consult the document), text (if you want to add an empty text field to be filled by the participant during the signature process), label (if you want to add a read only text on the document).
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.
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.
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.
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.
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 or label. If not provided, the height is set to font height.
width string optional The width of the field (expressed in PDF's default user space units). Set only if field type is text or label. 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 The text you want to display in the label field. Set only if field type is label.
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.

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_21xz",
  "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_Ogon",
  "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_Ogon",
  "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_a4zrqgPgMn94/documents/doc_aDo/fields/fld_Ogon \
-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 unitarily (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_a4zrqgPgMn94/signatures \
-d signer=jane@universign.com \
-d field=fld_JX2n
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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    } ],
    "reviews" : [ ],
    "captures" : [ ],
    "sequencing" : [ ],
    "editions" : [ ]
  },
  "actions" : [ {
    "id" : "act_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    } ],
    "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
}

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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ {
      "reviewer" : "carol@universign.com",
      "recipient" : "jane@universign.com"
    } ],
    "captures" : [ ],
    "sequencing" : [ ],
    "editions" : [ ]
  },
  "actions" : [ {
    "id" : "act_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "stalled" : false
  }, {
    "id" : "act_E4PODAEYbDPrb",
    "actor" : "carol@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_E4PODAEYbDPrb",
    "tasks" : [ {
      "type" : "review",
      "state" : "todo",
      "recipient" : "jane@universign.com",
      "document" : "doc_aDo"
    } ],
    "stalled" : false
  }, {
    "id" : "act_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    } ],
    "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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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",
    "schedule" : [ ],
    "ongoing_conversation" : false,
    "has_unread_message" : false,
    "state" : "open",
    "waiting_period" : 0,
    "full_name_type" : "suggestion"
  } ],
  "watchers" : [ ],
  "sealers" : [ ],
  "documents" : [ {
    "id" : "doc_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ ],
    "sequencing" : [ ],
    "editions" : [ {
      "editor" : "John@universign.com",
      "recipient" : "$Designation"
    } ]
  },
  "actions" : [ {
    "id" : "act_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "stalled" : false
  }, {
    "id" : "act_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    } ],
    "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 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 unitarily, 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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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",
    "schedule" : [ ],
    "ongoing_conversation" : false,
    "has_unread_message" : false,
    "state" : "open",
    "waiting_period" : 0,
    "full_name_type" : "suggestion"
  } ],
  "watchers" : [ ],
  "sealers" : [ ],
  "documents" : [ {
    "id" : "doc_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ ],
    "sequencing" : [ {
      "before" : "jane@universign.com",
      "after" : "jean@universign.com"
    } ],
    "editions" : [ ]
  },
  "actions" : [ {
    "id" : "act_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    } ],
    "stalled" : false
  }, {
    "id" : "act_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "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_a4zrqgPgMn94/participants \
-d email=jane@universign.com \
-d invitation_message=SampleMessage \
-d waiting_period=7
Arguments Type Description
email 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 level_2 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. Value is level1 (simple signature) or level2 (advanced signature), level0 (simple signature without authentication). Default value is level1. Note that the level0 signature depends 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",
  "full_name_type" : "suggestion",
  "waiting_period" : 7
}

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_a4zrqgPgMn94/participants/messages?email=jane@universign.com \
-X GET
Arguments Type Description
email 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_EvOYmKAq35gOv",
  "sent_at" : "2024-03-25T14:59:28Z",
  "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:

  1. sending a message to the participant.
  2. 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_a4zrqgPgMn94/participants/messages \
-d email=jane@universign.com \
-d message=Done
Arguments Type Description
email 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_EvOYmKAq35gOv",
  "sent_at" : "2024-03-25T14:59:28Z",
  "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
email 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_a4zrqgPgMn94/participants/remind \
-d email=jane@universign.com
Arguments Type Description
email 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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ ],
    "sequencing" : [ {
      "before" : "jane@universign.com",
      "after" : "jean@universign.com"
    } ],
    "editions" : [ ]
  },
  "actions" : [ {
    "id" : "act_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    } ],
    "stalled" : false
  }, {
    "id" : "act_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "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
}

Transaction archives

Archives endpoints

GET /v1/archives
GET /v1/archives/{transaction_id}
GET /v1/archives/{transaction_id}/requester-attestation

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_a4zrqgPgMn94/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.

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: level1 (simple signature), level2 (advanced signature). Default value is level1, level0 (simple signature without authentication).
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 Value is signature if the participant needs to sign the field or visa if the participant only needs to consult the document.
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 50 .
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_agMgvOzLya3k

Returns

The request returns a template object, as it was last updated.

Response example

{
  "object" : "template",
  "id" : "tpl_agMgvOzLya3k",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2023-10-02T09:07:07Z",
  "duration" : 20160,
  "template_name" : "New template",
  "folder_name" : "Default folder",
  "transaction_name" : "Contract John",
  "language" : "fr",
  "sender_name_display" : "name_email_issuing_entity",
  "creator" : {
    "name" : "Demo Workspace",
    "email" : "koussai.houssine@universign.com",
    "workspace_name" : "DemoWS"
  },
  "state" : "published",
  "publishable" : true,
  "participants" : [ {
    "email" : "$1709742207367",
    "designation" : "insured",
    "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"
  } ],
  "sealers" : [ ],
  "documents" : [ {
    "id" : "doc_0MDM",
    "name" : "Contract template.pdf",
    "name_locked" : true,
    "type" : "specimen",
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_b3m",
      "position" : {
        "page" : 2,
        "x" : 331,
        "y" : 415,
        "width" : 200,
        "height" : 50
      },
      "type" : "signature",
      "built_in" : false,
      "consents" : [ ],
      "optional_consents" : [ ],
      "updatable" : true,
      "deletable" : false
    } ],
    "editable" : true
  } ],
  "field_groups" : [ {
    "id" : "fld_b3m",
    "type" : "field",
    "fields" : [ "fld_b3m" ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "$1709742207367",
      "field" : "fld_b3m"
    } ],
    "reviews" : [ ],
    "captures" : [ ],
    "sequencing" : [ ],
    "editions" : [ ]
  },
  "actions" : [ {
    "id" : "act_w2EQlay9PM6Ky",
    "actor" : "$1709742207367",
    "tasks" : [ {
      "type" : "signature",
      "field" : "fld_b3m"
    } ]
  } ],
  "action_graph" : {
    "act_w2EQlay9PM6Ky" : [ "end" ],
    "start" : [ "act_w2EQlay9PM6Ky" ]
  },
  "metadata" : { },
  "carbon_copies" : [ ],
  "allow_carbon_copy" : false,
  "last_publication_date" : "2024-03-06T16:24:00Z",
  "last_publisher" : {
    "name" : "John DOE",
    "email" : "koussai.houssine@universign.com",
    "workspace_name" : "DemoWS"
  },
  "issuing_entity" : {
    "active" : true,
    "name" : "Test_entity",
    "id" : "iss_w9nmLe9qzYDy"
  }
}

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_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
      } ],
      "editable" : 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_dEn4XVq7G0bJ7",
      "actor" : "jane.doe@universign.com",
      "tasks" : [ {
        "type" : "signature",
        "field" : "fld_gg6M"
      } ]
    } ],
    "action_graph" : {
      "start" : [ "act_dEn4XVq7G0bJ7" ],
      "act_dEn4XVq7G0bJ7" : [ "end" ]
    },
    "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"
    }
  }, {
    "object" : "template",
    "id" : "tpl_agMgvOzLya3k",
    "folder_id" : "fol_JxmJlV5P922X",
    "created_at" : "2023-10-02T09:07:07Z",
    "duration" : 20160,
    "template_name" : "New template",
    "folder_name" : "Default folder",
    "transaction_name" : "Contract John",
    "language" : "fr",
    "sender_name_display" : "name_email_issuing_entity",
    "creator" : {
      "name" : "Demo Workspace",
      "email" : "koussai.houssine@universign.com",
      "workspace_name" : "DemoWS"
    },
    "state" : "published",
    "publishable" : true,
    "participants" : [ {
      "email" : "$1709742207367",
      "designation" : "insured",
      "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"
    } ],
    "sealers" : [ ],
    "documents" : [ {
      "id" : "doc_0MDM",
      "name" : "Contract template.pdf",
      "name_locked" : true,
      "type" : "specimen",
      "updatable" : true,
      "deletable" : false,
      "fields" : [ {
        "id" : "fld_b3m",
        "position" : {
          "page" : 2,
          "x" : 331,
          "y" : 415,
          "width" : 200,
          "height" : 50
        },
        "type" : "signature",
        "built_in" : false,
        "consents" : [ ],
        "optional_consents" : [ ],
        "updatable" : true,
        "deletable" : false
      } ],
      "editable" : true
    } ],
    "field_groups" : [ {
      "id" : "fld_b3m",
      "type" : "field",
      "fields" : [ "fld_b3m" ]
    } ],
    "instructions" : {
      "signatures" : [ {
        "signer" : "$1709742207367",
        "field" : "fld_b3m"
      } ],
      "reviews" : [ ],
      "captures" : [ ],
      "sequencing" : [ ],
      "editions" : [ ]
    },
    "actions" : [ {
      "id" : "act_eEJd3Zbg5LxnM",
      "actor" : "$1709742207367",
      "tasks" : [ {
        "type" : "signature",
        "field" : "fld_b3m"
      } ]
    } ],
    "action_graph" : {
      "act_eEJd3Zbg5LxnM" : [ "end" ],
      "start" : [ "act_eEJd3Zbg5LxnM" ]
    },
    "metadata" : { },
    "carbon_copies" : [ ],
    "allow_carbon_copy" : false,
    "last_publication_date" : "2024-03-06T16:24:00Z",
    "last_publisher" : {
      "name" : "John DOE",
      "email" : "koussai.houssine@universign.com",
      "workspace_name" : "DemoWS"
    },
    "issuing_entity" : {
      "active" : true,
      "name" : "Test_entity",
      "id" : "iss_w9nmLe9qzYDy"
    }
  } ]
}
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: level1 (simple signature), level2 (advanced signature). Default value is level1, level0 (simple signature without authentication).
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 Value is signature if the participant needs to sign the field or visa if the participant only needs to consult the document.
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 50 .
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. Can't 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

POST /v1/transactions/full

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
    }]
  } ],
  "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[ ].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.
documents[ ].fields[ ].type string optional Default value is signature. Pass visa if the participant only needs to consult the document.
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.
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.
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.
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.
documents[ ].fields[ ].consents array of strings optional 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. Set only if field type is signature or visa.
documents[ ].fields[ ].optional_consents array of strings optional 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. 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. Value is level1 (simple signature) or level2 (advanced signature), level0 (simple signature without authentication). Default value is level1. Note that the level0 signature depends 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 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.

Returns

Response example

{
  "object" : "transaction",
  "id" : "tx_kqY0QMwAg423",
  "folder_id" : "fol_DGX2qbq6yGmm",
  "created_at" : "2024-03-20T08:29:50Z",
  "started_at" : "2024-03-20T08:29:51Z",
  "expires_at" : "2024-03-31T02:49:51Z",
  "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_d9GXlK6qgPqEmiD5Bo9KEGMX8z",
    "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_n7ya",
    "name" : "MyDoc",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_654",
      "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
    }, {
      "id" : "fld_6Mzr",
      "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"
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "signer@domain.com",
      "field" : "fld_654"
    }, {
      "signer" : "signer2@mail.com",
      "field" : "fld_6Mzr"
    } ],
    "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_QZ3Kny0D7GqE1",
    "actor" : "reviewer1@mail.com",
    "state" : "open",
    "url" : "https://apps.trunk.universign.net/npds/act_QZ3Kny0D7GqE1",
    "tasks" : [ {
      "type" : "review",
      "state" : "todo",
      "recipient" : "signer@domain.com",
      "document" : "doc_n7ya"
    } ],
    "stalled" : false
  }, {
    "id" : "act_zwQKb4dB8w2wn",
    "actor" : "signer@domain.com",
    "state" : "waiting",
    "url" : "https://apps.trunk.universign.net/npds/act_zwQKb4dB8w2wn",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_654"
    } ],
    "stalled" : false
  }, {
    "id" : "act_YrDwbxBa52715",
    "actor" : "signer2@mail.com",
    "state" : "waiting",
    "url" : "https://apps.trunk.universign.net/npds/act_YrDwbxBa52715",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_6Mzr"
    } ],
    "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:

  1. via the /transactions endpoint
    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).

  2. via the /archives endpoint
    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_a4zrqgPgMn94/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='the document must be in color.'

To capture 2 iban

curl https://api.universign.com/v1/transactions/tx_a4zrqgPgMn94/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_a4zrqgPgMn94/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_a4zrqgPgMn94/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_a4zrqgPgMn94/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_a4zrqgPgMn94/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_a4zrqgPgMn94",
  "folder_id" : "fol_JxmJlV5P922X",
  "created_at" : "2024-03-25T14:59:21Z",
  "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" : true,
    "has_unread_message" : false,
    "state" : "open",
    "waiting_period" : 7,
    "full_name_type" : "suggestion"
  } ],
  "watchers" : [ ],
  "sealers" : [ ],
  "documents" : [ {
    "id" : "doc_aDo",
    "name" : "DocName",
    "editable" : true,
    "updatable" : true,
    "deletable" : false,
    "fields" : [ {
      "id" : "fld_JX2n",
      "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_1ZkX",
      "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",
      "required" : true,
      "font_size" : 12,
      "type" : "text"
    }, {
      "id" : "fld_lW9",
      "name" : "LabelField",
      "position" : {
        "page" : 1,
        "x" : 75,
        "y" : 200,
        "width" : 24,
        "height" : 16
      },
      "built_in" : false,
      "updatable" : true,
      "deletable" : true,
      "value" : "This",
      "font_size" : 10,
      "type" : "label"
    }, {
      "id" : "fld_21xz",
      "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
    } ]
  } ],
  "instructions" : {
    "signatures" : [ {
      "signer" : "jane@universign.com",
      "field" : "fld_JX2n"
    }, {
      "signer" : "jean@universign.com",
      "field" : "fld_21xz"
    } ],
    "reviews" : [ ],
    "captures" : [ {
      "actor" : "jane@universign.com",
      "document_type" : "identity_document",
      "accepted_identity_documents" : [ "passport", "identity_card" ],
      "total_items_required" : 2,
      "guideline" : "'the"
    } ],
    "sequencing" : [ {
      "before" : "jane@universign.com",
      "after" : "jean@universign.com"
    } ],
    "editions" : [ ]
  },
  "actions" : [ {
    "id" : "act_wPz99P4d52X8",
    "actor" : "jane@universign.com",
    "state" : "open",
    "url" : "https://apps.universign.com/npds/act_wPz99P4d52X8",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_JX2n"
    }, {
      "type" : "capture",
      "state" : "todo",
      "document_type" : "identity_document"
    }, {
      "type" : "capture",
      "state" : "todo",
      "document_type" : "identity_document"
    } ],
    "stalled" : false
  }, {
    "id" : "act_4JYWOlYknna1L",
    "actor" : "jean@universign.com",
    "state" : "waiting",
    "url" : "https://apps.universign.com/npds/act_4JYWOlYknna1L",
    "tasks" : [ {
      "type" : "signature",
      "state" : "todo",
      "field" : "fld_21xz"
    } ],
    "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:

  1. via the /transactions endpoint
    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).

  2. via the /archives endpoint
    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

GET v1/events/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.
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.

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

POST /v1/issuing-entities

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.
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

POST /v1/issuing-entities/{id}

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.
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

GET /v1/issuing-entities/{id}

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

POST /v1/issuing-entities/{id}/activate

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

POST /v1/issuing-entities/{id}/deactivate

This endpoint enables you to deactivate the workspace issuing entity.

Note that you can't 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

POST /v1/issuing-entities/{id}/retire

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

The API returns an empty 200 response.

Response example

List issuing entities

GET /v1/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

POST /v1/id-validations

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 to 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.

Request identity prevalidation

POST /v1/id-validations

This endpoint enables you to request the prevalidation of an identity document considering some constraints.

Request example

curl https://api.universign.com/v1/id-validations \
\
-d document=@test_cin_recto.png \
\
-d document=@test_cin_verso.png \
\
-d document_type="id_card:fra" \
\
-d full_name="John DOE" \
\
-d birthdate="2000-04-06"

Prerequisites

Before you send an identity document for prevalidation, you must ensure that it complies with the following prerequisites:

Note that we currently support only European IDs and passports.

Once you ensured the identity document complies with the prerequistes, you must send it to Universign using a multipart/form-data request type (as shown in the code panel), and optionally set a series of parameters that you should pass as arguments, as follows:

Arguments Type Description
document multipart file required The identity document to be prevalidated. Allowed formats are JPEG, PNG, GIF and PDF.
document_type array of string required Used to restrict the type(s) of accepted IDs. The document_type type concatenates the category of the identity document and its country code. Value(s) can be id_card:fra for French ID cards, passport:* for passports (replace * with the three-letter country code corresponding to the accepted country. If you accept all European passports, replace * with eu. View the list of ISO 3166-1 alpha-3 codes here.
email string required The identity document holder's email.
full_name string required The identity document holder's full name.
birthdate string required The identity document holder's birthdate. Expected format is YYYY-MM-DD.
expires_after string optional The date after which the identity document is allowed to be expired. Expected format is YYYY-MM-DD.
allow_manual_validation boolean optional Set to true if you want the identity document to be manually prevalidated in case the automatic prevalidation process fails.

Returns

Response examples

For a successful prevalidation

{
    "object": "id-validation",
    "id": "idval_JxYxqqrdZOrn",
    "status": "success",
    "verification": {
        "successful_checks": [
            "color",
            "expires_after",
            "name",
            "age",
            "birth_date"
        ],
        "failed_checks": []
    }
}

If prevalidation succeeded
You are returned a 200 response with a prevalidation ID. Please note that the prevalidation ID will expire 7 days after issuance. Also, note that a successful prevalidation may lead to a failed certificate issuance if the identity document expires between the prevalidation date and the certificate issuance date. To avoid such occurrence, you can require an identity document to be valid beyond the current date through the expires_after parameter.

For a failed prevalidation due to an extraction problem

{
    "object": "id-validation",
    "id": "idval_w9Jb930GbwGP",
    "status": "extraction_failure",
    "verification": {
        "extraction_failure_reason": "inconsistent_data",
        "extraction_failure_fields": [
            "optical_lines"
        ],
        "successful_checks": [],
        "failed_checks": []
    }
}

If prevalidation failed due to an extraction problem
You are returned a 200 response with a prevalidation ID as well as the first reason for failure that was encountered during the extraction process. In general, to avoid failed extraction occurrences, check that the uploaded document complies with our prerequisites. Possible extraction failure reasons are listed in the table below:

Reason Definition Troubleshooting
missing_side A side of the document is missing. Make sure you provide all expected sides of the identity document in your request.
unidentified_side A side of the document is not recognized by the system. The document quality or the image quality may be the cause. Alternatively, check that the document you provided is an accepted type of ID.
too_many_sides You sent too many sides in the request. Make sure you upload only one identity document per request.
incompatible_sides You sent a document that contains incompatible sides. To be compatible, two sides must belong to the same document type (French identity card for example) and be a different side (front and back).
missing_data One or more expected fields cannot be extracted. The document quality or the image quality may be the cause.
inconsistent_data Some of the extracted data is inconsistent. Alternatively, front and back sides are inconsistent with each other. The document or image quality might be the cause, or you submitted two files belonging to two different identity documents. Alternatively, the document may be fraudulent.

For a failed prevalidation due to data mismatching

{
    "object": "id-validation",
    "id": "idval_D9y9X913vQBA",
    "status": "constraints_failure",
    "verification": {
        "successful_checks": [
            "color",
            "expires_after",
            "age"
        ],
        "failed_checks": [
            "name",
            "birth_date"
        ]
    }
}

If prevalidation fails because the data extracted does not match the constraints you defined
You are returned a 200 response with a prevalidation ID, as well as a detailed list of failed and successful constraints checks. Please check and update your ID holer's data accordingly before you send the document for prevalidation again.

Note: If you set allow_manual_validation to true, and the automatic prevalidation fails, you are returned a 200 response with a pending_manual_validation status.

For a failed prevalidation with manual validation allowed

{
  "object": "id-validation",
  "id": "idval_D9y9X913vQBC",
  "status": "pending_manual_validation"
}

Certificate matching

Advanced signatures (level2 and higher) require the participant to have a certificate. So, before creating a transaction, you may need to know if your participant has a valid (neither expired nor revoked) certificate.

Retrieve certificate matching

This endpoint enables you to know if your participant has at least one valid certificate to perform an advanced signature.

GET v1/certificates/match

Request example

curl https://api.universign.com/v1/certificates/match?email=john@universign.com
Arguments Type Description
email string required The participant email address.
min_certificate_level string optional Minimum certificate level required for the match, among lcp (Lightweight Certificate Policy) or qcp (Qualified Certificate Policy).
fullname string optional The participant full name.
phone_number string optional The participant phone number. Expected format is E.164 ([+][country code][phone number including area code]).

Returns

The API returns a match_found field.

Response example

{
  "match_found": true
}
cURL