Create Session

Initiates a HotDocs Embedded interview/assembly session and returns the 32-character session ID. This session ID can be used in conjunction with the Embedded JavaScript API to create and initialize an IFRAME in the web browser containing the requested interview or interviews.

Using Create Session

Creating an Embedded Interview Session using Create Session returns a Session ID. This Session ID must then be used with the CreateInterviewFrame Embedded JavaScript API method to generate an Embedded Interview IFRAME.

NewSession POST

HTTP Request

POST https://{subscribedEndpoint}/embed/newsession/{subscriberID}/{packageID}

Parameters

Name	Location	Required	Description
subscribedEndpoint	path	Yes	The endpoint to which the caller is subscribed. This is either: USA – cloud.hotdocs.ws EU – europe.hotdocs.ws
subscriberID	path	Yes	The caller's Cloud Services subscriber ID
packageID	path	Yes	A version-specific ID identifying the template package for which you are requesting an interview/assembly session.
answers	request body	No	XML answers to be pre-populated in the interview can be supplied in the request body.
date	HTTP header or query string	Yes	The date and time (in UTC) of the request, formatted according to RFC 1123. This date can be included either as a parameter on the query string or in an "x-hd-date" (custom) HTTP header.
signature	HTTP header or query string	Yes	The base64-encoded HMAC calculated using the parameters of this request. Note: the HMAC must be included in an "Authorization" HTTP header. See HMAC Calculation for Create Session for more information.
interviewformat	query string	Yes	The interview format requested
outputformat	query string	Yes	The output format requested
markedvariables	query string	No
showdownloadlinks	query string	No	"true" or "false", depending on whether download links for assembled documents should be presented directly to the end user or not. If download links are not shown, you must initiate retrieval of assembled documents using the onDocumentsAssembled or onSessionCompleted call-back functions described in the HotDocs Embedded JavaScript API.
theme	query string	No	The name of an interview theme as defined in the Administrative Portal for this subscriber ID. See Using Themes for Embedded Interviews for more details.
billingRef	query string	No	This parameter lets you specify information that will be included in usage logs for this call. For example, you can use a string to uniquely identify the end user that initiated the request and/or the context in which the call was made. When you later review usage logs, you can then see which end users initiated each request. That information could then be used to audit or pass costs on to those end users if desired.
RetrieveFromHub	query string	No	Enables you to retrieve a HotDocs template from the HotDocs Hub instead of a template stored in the Cloud Services cache. Select from the following options (case-insensitive): No (default value) – do not connect to HotDocs Hub; use the Package ID in request path (see above) to get the template from the Cloud Services cache ByTemplateId – use the Package ID in request path as the ID of the template to retrieve. Cloud Services checks the HotDocs Hub for the latest version of the template and: If the Cloud Services cache has the latest version of the template, the template is retrieved from the cache. If the Cloud Services cache does not have the latest version of the template, the latest version of the template is retrieved from the HotDocs Hub. The Cloud Services cache is updated with the template retrieved from the HotDocs Hub. ByVersionId – use the Package ID in request path as the ID of the specific template Version to retrieve. Cloud Services checks the HotDocs Hub for the specific version of the template and: If the Cloud Services cache has the same version of the template as the Hub, the template is retrieved from the cache. If the Cloud Services cache does not have the same version of the template as the hub, the specific version of the template is retrieved from the HotDocs Hub. The Cloud Services cache is updated with the template retrieved from the HotDocs Hub.
(additional settings)	query string	No	You can also optionally include on the query string any interview or assembly settings from those listed in either GetInterviewOptions.Settings or AssembleDocumentOptions.Settings. Settings specified on the query string will override the defaults designated in the Cloud Services administration portal.

Example URL

https://cloud.hotdocs.ws/embed/newsession/examplesubscriber/353c1217-09a6-42db-b84e-385ead9c87b0?signature=MoU1g8gyEEXxbJkeU+g4BsZAnn8=

Response

If successful, this method returns a 32-character Session ID. The Session ID is used with CreateInterviewFrame JavaScript function to create the Interview.

Request Headers

When making aCreate Session request to Cloud Services, the request must include the following headers.

Name	Data Type	Data	Description	Example (C#)
x-hd-date	DateTime value	2015-01-31T08:55:19Z	A Date and Time for the request. This should be the same value as the date/time used when calculating the HMAC.	request.Headers.Add("x-hd-date", timestamp.ToString("yyyy-MM-ddTHH:mm:ssZ"));
Authorization	string	The calculated HMAC	The HMAC used to sign the request.	request.Headers.TryAddWithoutValidation("Authorization", hmac);
Content-Type (optional)	text/plain		(Optional) HotDocs Answer XML, used to pre-populate the fields in an interview.	request.Content.Headers.Add("Content-Type", "text/plain");

HMAC Calculation for Create Session

For calls to create a session, the HMAC is calculated from the following list of parameters:

Name	Type	Example Data	Description
signingKey	string	example-signing-key	The Signing Key assigned to your Cloud Services account. You can find your Signing Key by logging in to the Cloud Services Portal.
date	DateTime	2015-01-31T08:55:19Z	Date and time, using the format "yyyy-MM-ddTHH:mm:ssZ". For example, a datetime of 31/05/2015 08:55:19 is formatted as 2015-01-31T08:55:19Z.
subscriberID	string	ExampleCompany	Subscriber ID named used to connect to Cloud Services. This was provided when you signed up to Cloud Services.
packageID	string	ExamplePackage1	The name of the HotDocs Package File (.hdpkg) uploaded to Cloud Services.
billingRef	string	ExampleCustomer, Template Upload	Lets you specify information that will be included in usage logs for this call. For example, you can use a string to uniquely identify the end user that initiated the request and/or the context in which the call was made. When you later review usage logs, you can then see which end users initiated each request. That information could then be used to audit or pass costs on to those end users if required.
interviewformat	string	JavaScript	The interview format requested.
outputformat	string	DOCX	The output format requested.
additional settings	string		Any optional settings that were included in the query string of the request (see above).

Example (C#)

Walkthrough

For a full walkthrough of using the .Net Client Library to generate an interview/assembly session, see Cloud Services Embedded Example 1: Display an Interview.

Code

For a full example of using the REST API to generate an interview/assembly session, see the CloudServicesEmbeddedAPIExample project in the HotDocs Integration Examples.