Creating a Work Item

The Create work item API method enables you to create a work item in an existing work group. You can choose to pre-populate the work item with answer data.


Before making a 'create work item' 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 in which you are creating the work item

  • A work group  – the ID of a work group in your tenancy is required when making the request
  • A template package – the ID of a template package uploaded to your tenancy is required when making the request


The 'create work item' 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 provide users with a new work item that is pre-populated with a set of answers sourced from another system. Users can then modify the answer data in the work item according to their needs. In the method call, you supply answer data in the form of HotDocs Answer XML.

Work items created using the API are marked with a New work item icon icon in the Advance UI. This tells users that the work item has been created but its answers are not yet updated.

Validating the HotDocs Answer Set XML

When sending HotDocs answer set XML in a create work item 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}


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 A new Guid to identify the work item. The ID cannot be the same as that of an existing work item.
name String Request body   Yes A unique name for the work item. The name cannot be the same as that of an existing work item.
description String Request body   No

A friendly description for the work item.

workGroupId Guid Request body   Yes The ID for an existing work group.
templatePackageId Guid Request body   Yes The ID for an existing template package. The template package must be:
  • Activated; and
  • Assigned to the work group specified above
The live version of the template package is always used to create the work item.
answerXml string Request body 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. You can omit this parameter if you do not want to pre-populate the work item with answer data.
assembleImmediately Boolean Request body No

Determines if Advance runs an assembly session to produce completed documents as soon as the new work item is created.

completeAssemblySession Boolean Request body No Set the status of assembly session for the work item to Complete. If a user opens the work item in the UI, they will not be prompted to open the interview (i.e. with the "You have an unfinished interview in progress" message).
isPrivateToOwner Boolean Request body No Set the privacy status of the new work item. Either:
  • True – the work item is Private and can only be accessed by the owner; or
  • False – the work item is Public and is accessible to other users that have access to the specified work group, set by the workGroupId parameter.


Example Request URL

Example Request JSON


    "name": "ExampleCorp contract renewal",

    "description": "Updating the contract for ExampleCorp.",

    "workGroupId": "cb97f8d6-04a1-490a-aa09-92af12dfb305",

    "templatePackageId": "0ef6a9be-b007-4d7d-83f1-9d56f931cd0f",

    "answerXml": "<AnswerSet title='' version='1.1' useMangledNames='false'><Answer name='CompanyName'><TextValue>ExampleCorp</TextValue></Answer></AnswerSet>",

    "assembleImmediately": true,

    "completeAssemblySession": false,

    "isPrivateToOwner": true


Example Response

Status: 200 OK

Code Example

See Create Work Item Example for further examples.


using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
namespace HotDocsAdvanceApiExamples
    public class WorkItemRequest
        public async Task<HttpStatusCode> CreateWorkItem(string token)
            // Create the 'create work item' request  
            var workItemId = Guid.NewGuid();
            var request = CreateHttpRequestMessage(workItemId);
            //Send create user request to Advance
            using (var client = new HttpClient())
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                var response = await client.SendAsync(request);
                return response.StatusCode;
        private HttpRequestMessage CreateHttpRequestMessage(Guid workItemId)
            // Create the request for the 'create work item' API endpoint
            var createWorkItemUrl = string.Format("{0}", workItemId);
            return new HttpRequestMessage
                RequestUri = new Uri(createWorkItemUrl),
                Method = HttpMethod.Put,
                Content = GetRequestContent()
        private StringContent GetRequestContent()
            // Generate the JSON request body required by the 'create user' method
            var json = "{\"name\": \"Example Contract A\",\"templatePackageId\": \"03000000-0000-0000-0000-000000000003\",\"workGroupId\": \"09000000-0000-0000-0000-000000000001\",\"answerXml\": \"<answerset title="\'\'" version="\'1.1\'" usemanglednames="\'false\'"><answer name="\'ClientName\'"><textvalue>Bob Sherunkle</textvalue></answer></answerset>\",\"assembleImmediately\": true, \"completeAssemblySession\": false, \"isPrivateToOwner\": true}";
            return new StringContent(json, Encoding.UTF8, "application/json");