Begin an Assembly Session

The begin assembly session API method enables you to create a new assembly session for a work item.


Before making an 'begin assembly session' request, you must have an access token to sign the request. You can retrieve an access token using one of the following flows:

Additionally, you must have the following items in the tenancy for which you are creating an assembly session:


The 'begin assembly session' API method is a command method. The API client invoking this method must have either a command or a root scope.

This method is useful when you want to display a HotDocs interview or assemble documents from within your own application.

Validating the HotDocs Answer Set XML

When sending HotDocs answer set XML in a begin assembly session request, you must first validate the answer set against the HotDocs answer Set schema.


See Authentication for more information about authenticating requests to the Advance API.

API Documentation

You can view the latest documentation for the Advance API at


Request URL

PUT https://{tenancymoniker}{id}/Versions/{versionId}


Key Required Description Example value
Authorization Yes The Authorization header for the request. Uses the access token retrieved (see Prerequisites section above for more information). Bearer [access token]


Name Type Location Required Description
tenancymoniker String


Yes The tenancy moniker for the tenancy in which you want to create the new work item.
id Guid


Yes The Guid for an existing work item.
versionId Guid


Yes A new Guid, used to identify the assembly session in Advance.
answerXml String


No A HotDocs answer set, containing an initial set of answer data to be used by the assembly session. This is a string of XML that validates against the HotDocs answer set schema. If you are using the batch processing workflow, it is likely that you will always want to include answer XML data.
forceCreate Boolean


No If true, the request forces Advance to create a new assembly session, even if there is already an in-progress assembly session for the work item. The existing in-progress assembly session is deleted. If you omit this parameter, the default behavior of Advance is to treat this parameter as false: You will receive a 409 Conflict error informing you that there is an existing in-progress assembly session.


Example Request URL

Example Request JSON


Example Response

Status: 200 OK



    "hdaSessionId": "32b701fa-fh73-4d58-a70c-71e27c277df9",

    "coreSessionId": "mntekqe11s9w3rhe7u3rfdxws3ur1fhdpo68j74rpw6ofmkcoyn9ene3dzz84bnrh7qcy35geon855o7drgsahi3t9ba8yhg",

    "interviewJsUrl": "",

    "serviceMetadataUrl": ""


Using the Response Data

The begin assembly session method provides the following data in its response:

Name Type Description Example data
hdaSessionId Guid Identifies the assembly session within Advance. You will need this ID when using other API methods that interact with the assembly session. For example, the save, delete, and complete assembly session endpoints.


coreSessionId Guid Identifies the assembly session within the Core Assembly Service. You will need this ID when using HD$.AttachSession to display the interview in a user's browser. mntekqe11s9w3rhe7u3rfdxws3ur1fhdpo68j74rpw6ofmkcoyn9ene3dzz84bnrh7qcy35geon855o7drgsahi3t9ba8yhg
interviewJsUrl String The URL from which to load the interview.js file. You must include this in the page on which the interview is displayed.
serviceMetadataUrl String The URL for the current assembly session in the Core Assembly Service.

You will require this data when displaying an interview.

Resuming a Saved Assembly Session

If you have already saved an assembly session, you can resume the session by making a request to the begin assembly session endpoint, using same versionId you used to begin the initial assembly session. When making the request, ensure that you set the request body parameters as follows:

  • answerXml (string) – you must omit this parameter; Advance will reload the answers from your saved assembly session into the resumed assembly session
  • forceCreate (boolean) – you must set this parameter to true

Code Example


Note: this code example assumes that you are using .Net Framework 4.6 and a new ASP.NET Web Application project. You will build upon this project in the later code examples for displaying an interview and completing an assembly session.


using System.Web.Mvc;
using System.Threading.Tasks;
namespace AdvanceExampleApplication.Controllers
    public class HomeController : Controller
        public async Task<ActionResult> Index()
            // You should have already implemented the 'ResourceOwnerAuthorization' method in the 'Getting an Access Token using the Resource Owner flow' topic.
            var token = await ResourceOwnerAuthorization.GetResourceOwnerToken();
            var assemblySessionData = await AssemblySessionHandler.BeginAssemblySession(token);
            return View();


using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
namespace AdvanceExampleApplication
    public static class AssemblySessionHandler
        public static async Task<AssemblySessionDto> BeginAssemblySession(string token)
            // ID of a work item for which you want to create the assembly session;
            // it must not have an in-progress assembly session
            var workItemId = Guid.Parse("a1e0e795-5a51-44f5-8fe2-e85a61dbf3c2");
            // Create the request
            var request = CreateHttpRequestMessage(workItemId);
            // Send the begin assembly session request to Advance
            using (var client = new HttpClient())
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                var response = await client.SendAsync(request);
                return JsonConvert.DeserializeObject<assemblysessiondto>(await response.Content.ReadAsStringAsync());
        private static HttpRequestMessage CreateHttpRequestMessage(Guid workItemId)
            var assemblySessionId = Guid.NewGuid();
            var assemblySessionUrl = $"{workItemId}/Versions/{assemblySessionId}";  
            var body = new
                forceCreate = true,
                answerXml = string.Empty
            return new HttpRequestMessage
                RequestUri = new Uri(assemblySessionUrl),
                Method = HttpMethod.Put,
                Content = new StringContent(JsonConvert.SerializeObject(body), Encoding.UTF8, "application/json")


namespace AdvanceExampleApplication
    public class AssemblySessionDto
        public string InterviewJsUrl { get; set; }
        public string HdaSessionId { get; set; }
        public string CoreSessionId { get; set; }
        public string ServiceMetadataUrl { get; set; }

Next Steps