Overview and Request Content

Overview

This API is used to trigger a new EasySend transaction. When triggered, a Start email/SMS will be sent to the specified customer according to the configuration and the API endpoint that is being used.

In addition, the API returns a link to the digital process transaction. The created link will contain a unique request ID that ensures all prefilled data is embedded in the link and can only be submitted once before expiry.

URL Path

player/api/generate-link - generate a digital process link
player/api/send-link - generate a digital process link with customer notification

Method

A POST request should be performed with the following HTTP Header: Content-Type: application/json.

Authentication Using apiKey Field

The apiKey allows EasySend to use a simple authentication mechanism that is used to authenticate the client against the server. The apiKey must be passed with every API call.

Warning!

Your apiKey is private and should always be kept secret. Never share your API key with a 3rd party. Always trigger EasySend APIs from a server-side application. Avoid embedding your API key in a client-side / web-based application.

Request Content

Table 1 describes the required request content parameters.

Table 1: Request Content

Parameter	Type	Optional/Required	Discerption
apiKey	string	Required	The API key for the provided environment
customerId	string	Required	As given by EasySend
processId	string	Required	The unique ID of the process
variant	string	Optional	Can be used to generate the process with a specific theme variant
source	string	Optional	Set the source field for the digital process metadata
serializedModel	object	Optional	All the model fields are according to the journey sender’s model NOTE To learn how to export initiation payload, see the Export Initiation Payload section
role	string	Optional	The role to be used for the first step of the digital workflow
brand	string	Optional	Brand name as configured in the URLs for the environment; will be used to create a URL with the configured domain for that brand
EnableRtSync	boolean	Optional	Determines if the link that was sent will be active with Co-browsing: True - Co-browsing is on False - Co-browsing is off If the parameter is not specified, the Co-browsing behavior will be determined according to the server's configuration
runAsync	boolean	Optional	Set to true for link generation to run asynchronously

Export Initiation Payload

You can export an EasySend process payload and use it to initiate a process through the API. The payload mirrors the structure of the process's Model and data items and is exported as a JSON file. To learn more, click here.

Sample Calls

{
    "apiKey": "[your-API-key]",
    "customerId": "y-company",
    "processId": "Ffb2g752chqBfNYk70Fp",
    "serializedModel": {
        "personalDetails": {
            "firstName": "John",
            "lastName": "Smith"
        }
    }
}

When calling this API asynchronously, for long processes or processes that may include heavy computation tasks, the runAsync=true parameter must be added:

{
    "apiKey": "[your-API-key]",
    "customerId": "y-company",
    "processId": "Ffb2g752chqBfNYk70Fp",
    "serializedModel": {
        "personalDetails": {
            "firstName": "John",
            "lastName": "Smith"
        }
    },
    "enableRtSync": false,
    "runAsync": true
}

Return Values

The HTTP status code will determine the success/failure of the response. The return code 200 is a success, and any other return code is considered an error. A successful request will contain a JSON request body as follows:

{
	“link”: <generated link to EasySend form>,
	“rid”: <generated unique request ID>,
    “masterRid”: <generated unique request ID>
}

NOTE

The masterRid provides a consistent identifier for the entire digital journey, even when it spans multiple webflows. The rid identifies individual transaction instances.

When sending an asynchronous request, the response will look like this:

{
    "taskId": "7309d641-8f2e-43bd-91f3-b3290447e6f7",
    "taskState": "STARTED"
}

To poll the task status, use /api/poll/<task-id> api. The poll response will include the task state, and if it succeeds, the generated link response (in the taskData field):

{
     "taskId": <task id>,
     "taskState": "SUCCESS",
     "taskData": "{
     “link”: <generated link to EasySend form>,
     “rid”: <generated unique request ID>,
     “masterRid”: <generated unique request ID>
     }"
}