Creating Handover URLs

A Handover URL is a redirect link pre-set in the transaction settings, which allows you to determine where the Signer Experience will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing. The Handover URL is displayed as an exit button on the global actions bar and on the tool bar.

Handover URLs can also be used as a web hook to send real-time messages to your endpoints about the triggered event. Once the signer hit the Handover URL link, additional parameters will be attached to the link, including “package”, “signer” and “status”.

For example, if you specified the Handover URL as:

https://yourdomain/oss/handover

After the recipient with signer ID of Signer1 has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like this:

https://yourdomain/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE

Handover URLs can be defined at the following levels:

• Package

• Account

• Language

By Package

To define a Handover URL at the package level there are three values you need to specify in the package settings:

• Handover Link Href: Defines the redirect URL to which the signer will be sent.

• Handover Link Text: The text that will appear on the handover button.

• Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

The following code shows you how to edit the settings block when creating a package.

.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
			            .withHandOverLinkHref("https://www.google.com")
	          .withHandOverLinkText("Exit to site")
	    .withHandOverLinkTooltip("You will redirected to Google homepage")
              )

By Account

As the Handover URL is a package setting, it is possible to set default Handover URL at the account level. If your work flow requires you to redirect the Signer Experience to a general completion page, or to your organization’s website, contact our Support Team and supply them with the following:

• Handover Link Href: Defines the redirect URL to which the signer will be sent.

• Handover Link Text: The text that will appear on the handover button.

• Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

Once this is done any new package that you create will have these default values.

By Language

Different Handover URLs can be specified for different languages. For example, if you have a multilingual site and want to navigate the signer to different language versions according to the signer's language. To do this, you can contact our Support Team and have different Handover URLs configured on your account.

You can also customize Handover URLs using SDKs. The following code sample demonstrates how to leverage the AccountConfigService class to specify the Handover URL for each Java Locale.

AccountConfigService accountConfigService = eslClient.getAccountConfigService();
				Handover handoverAfterCreating = accountConfigService.createHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withHref("https://www.google.com ")
				.withText("Exit to site ")
				.withTitle("You will redirected to Google homepage ")
				.build()
			);

Finding an existing language configuration

If you want to know if there’s any existing configurations defined for a language, use the following code:

Handover handoverExisting = accountConfigService.getHandoverUrl(java.util.Locale.ENGLISH);

Updating an existing language configuration

To update an existing language configuration, use the .updateHandoverUrl() function:

Handover  handoverAfterUpdating = accountConfigService.updateHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withTitle(“The updated tooltip”)   
				.build()
				);;

Deleting an existing language configuration

To delete a Handover URL setting use the following code:

accountConfigService.deleteHandoverUrl(java.util.Locale.ENGLISH);

A Handover URL is a redirect link pre-set in the transaction settings, which allows you to determine where the Signer Experience will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing. The Handover URL is displayed as an exit button on the global actions bar and on the tool bar.

Handover URLs can also be used as a web hook to send real-time messages to your endpoints about the triggered event. Once the signer hit the Handover URL link, additional parameters will be attached to the link, including “package”, “signer” and “status”.

For example, if you specified the Handover URL as:

https://yourdomain/oss/handover

After the recipient with signer ID of Signer1 has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like:

https://yourdomain/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE

Handover URLs can be defined at the following levels:

• Package

• Account

• Language

By Package

To define a Handover URL at the package level there are three values you need to specify in the package settings:

• Handover Link Href: Defines the redirect URL to which the signer will be sent.

• Handover Link Text: The text that will appear on the handover button.

• Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

The following code shows you how to edit the settings block when creating a package.

.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
				.withHandOverLinkHref("https://www.google.com")
				.withHandOverLinkText("Exit to site")
			.withHandOverLinkTooltip("You will redirected to Google homepage")
              )

By Account

As the Handover URL is a package setting, it is possible to set default Handover URL at the account level. If your work flow requires you to redirect the Signer Experience to a general completion page, or to your organization’s website, contact our Support Team and supply them with the following:

• Handover Link Href: Defines the redirect URL to which the signer will be sent.

• Handover Link Text: The text that will appear on the handover button.

• Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

By Language

Different Handover URLs can be specified for different languages. For example, if you have a multilingual site and want to navigate the signer to different language versions according to the signer's language. To do this, you can contact our Support Team and have different Handover URLs configured on your account.

You can also customize Handover URLs using SDKs. The following code sample demonstrates how to leverage the AccountConfigService class to specify the Handover URL for each Java Locale.

AccountConfigService accountConfigService = eslClient.getAccountConfigService();
				Handover handoverAfterCreating = accountConfigService.createHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withHref("https://www.google.com ")
				.withText("Exit to site ")
				.withTitle("You will redirected to Google homepage ")
				.build()
			);

Finding an existing language configuration

If you want to know if there’s any existing configurations defined for a language, use the following code:

Handover handoverExisting = accountConfigService.GetHandoverUrl(“en”);

Updating an existing language configuration

To update an existing language configuration, use the .updateHandoverUrl() function:

Handover  handoverAfterUpdating = accountConfigService.updateHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withTitle(“The updated tooltip”)   
				.build()
			);

Deleting an existing language configuration

To delete a Handover URL setting use the following code:

accountConfigService.deleteHandoverUrl(java.util.Locale.ENGLISH);

A Handover URL is a redirect link pre-set in the transaction settings, which allows you to determine where the Signer Experience will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing. The Handover URL is displayed as an exit button on the global actions bar and on the tool bar.

Handover URLs can also be used as a web hook to send real-time messages to your endpoints about the triggered event. Once the signer hit the Handover URL link, additional parameters will be attached to the link, including “package”, “signer” and “status”.

For example, if you specified the Handover URL as:

https://yourdomain/oss/handover

After the recipient with signer ID of Signer1 has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like:

https://yourdomain/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE

Handover URLs can be defined at the following levels:

• Package

• Account

• Language

By Package

To define a Handover URL at the package level there are three values you need to specify in the package settings:

• Handover Link Href: Defines the redirect URL to which the signer will be sent.

• Handover Link Text: The text that will appear on the handover button.

• Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

These attributes are hosted in the package JSON at “settings” > “ceremony” > “handOver”. The following codegives you an idea how you can build the “settings” node and include the handover URL information when creating a package:

{
				"status": "DRAFT",
				"settings": {
				"ceremony": {
				  "handOver": {
				        "title": "You will be redirected to Google homepage",
			        	"href": "http://www.google.com",
				        "text": "Exit to site"
				}
				    }
			},
			"type": "PACKAGE",
			"name": "Customized Signer Experience"
	}

By Account

As the Handover URL is a package setting, it is possible to set default Handover URL at the account level. If your work flow requires you to redirect the Signer Experience to a general completion page, or to your organization’s website, contact our Support Team and supply them with the following:

• Handover Link Href: Defines the redirect URL to which the signer will be sent.

• Handover Link Text: The text that will appear on the handover button.

• Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

By Language

Different Handover URLs can be specified for different languages. For example, if you have a multilingual site and want to navigate the signer to different language versions according to the signer's language. To do this, you can contact our Support Team and have different Handover URLs configured on your account.

You can also customize Handover URLs using REST APIs.

To create a Handover URL setting, use the following API.

HTTP Request

POST /api/accountConfig/handoverUrl/{language_code}

HTTP Headers

Accept: application/json 
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
            "title": "You will be redirected to Google homepage",
            "href": "http://www.google.com",
            "text": "Exit to site"
              

Finding an existing language configuration

If you want to know if there’s any existing configurations defined for a language, use the following code:

HTTP Request

GET /api/accountConfig/handoverUrl/{language_code}

HTTP Headers

Accept: application/json 
Authorization: Basic api_key

Response Payload

{
              "title": "You will be redirected to Google homepage",
              "href": "http://www.google.com",
            "text": "Exit to site"
}  

Updating an existing language configuration

Once you’ve created a setting, you can use the API below to update any partial attributes:

HTTP Request

PUT /api/accountConfig/handoverUrl/{language_code}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "title": "You will be redirected to Google homepage"
   }  

Deleting an existing language configuration

To delete a Handover URL setting use the following code:

HTTP Request

DELETE /api/accountConfig/handoverUrl/{language_code}

HTTP Headers

Authorization: Basic api_key