Client Return URL

The ClientReturnUrl property on the ParticipantInsertModel allows you to define a custom URL that the participant will be redirected to when they complete their tasks, cancel, or experience an error. This gives you full control over the messaging and user experience on your own website instead of relying on the default AlphaTrust e-Sign pages.

Overview

By default, when a participant finishes signing, cancels, or encounters an error, they are shown a standard AlphaTrust status page. By setting the ClientReturnUrl, you can redirect them to your own application where you control the messaging, branding, and next steps.

The ClientReturnUrl works in conjunction with the following behavior type properties on the participant:

• CompletedDocumentBehaviorType — Controls what happens after the participant completes their tasks. Set to RedirectToClientReturnUrl to redirect upon completion.
• CancelledTaskBehaviorType — Controls what happens when the participant cancels. Set to RedirectToClientReturnUrl to redirect upon cancellation.
• ErrorBehaviorType — Controls what happens when the participant experiences an error. Set to RedirectToClientReturnUrl to redirect upon error.

API Implementation

Setting the Client Return URL

When creating a transaction or inserting a participant, set the ClientReturnUrl property along with the appropriate behavior types:

var participant = new ParticipantInsertModel()
{
    TransactionID = 1234567890,
    FullName = "John Smith",
    EmailAddress = "john.smith@example.com",
    SendRequestViaEmail = true,
    ClientReturnUrl = "https://www.yourwebsite.com/signing-status",
    CompletedDocumentBehaviorType = "RedirectToClientReturnUrl",
    CancelledTaskBehaviorType = "RedirectToClientReturnUrl",
    ErrorBehaviorType = "RedirectToClientReturnUrl"
};

JSON Example

{
    "Participants": [
        {
            "TransactionID": 1234567890,
            "FullName": "John Smith",
            "EmailAddress": "john.smith@example.com",
            "SendRequestViaEmail": true,
            "ClientReturnUrl": "https://www.yourwebsite.com/signing-status",
            "CompletedDocumentBehaviorType": "RedirectToClientReturnUrl",
            "CancelledTaskBehaviorType": "RedirectToClientReturnUrl",
            "ErrorBehaviorType": "RedirectToClientReturnUrl"
        }
    ]
}

Handling the Redirect

When a participant is redirected to your ClientReturnUrl, AlphaTrust appends query string parameters to the URL so you can determine the context of the redirect. This includes a short-lived ps_securitytoken parameter that you should use to verify the authenticity of the request.

For details on validating the security token and securing your redirect endpoint, see Securing URL Redirects and API Interactions.