Reference Topic

Creating and Assembling a Work Item Version

API Version: v2.0
Method: PUT
Endpoint: /WorkItems/{workItemId}/Versions/{versionId}/CreateAndAssemble

This method creates a new work item version and immediately assembles documents in a single operation.  Use this method to reduce API calls in batch processing or automated workflows.

Overview

Instead of calling separate endpoints to create a version and then assemble documents, this method combines both steps. The assembled documents and updated answer set are available after the request completes.

Prerequisites

Before making a 'create and assemble' request, you must have an access token to sign the request. You can retrieve an access token using one of the following flows:

• Getting an access token using the Resource Owner flow
• Getting an access token using the Implicit flow

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.

Authentication

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

API Documentation

Operation Modes

You can choose how this endpoint operates:

Asynchronous callback

Provide an optional callbackUrl. The endpoint returns immediately with a status of Completing. Your callback URL will receive a notification when the operation finishes.

Synchronous - with polling fallback

If no callbackUrl is specified the endpoint operates synchronously until a system-configured threshold is exceeded. The default is 20 seconds.

• If completion finishes within this time, the status is returned in the response.
• If it takes longer, a URL for the work item version's status is returned for polling: GET {workItemId}/Versions/{versionId}/Status

Request

Request URL

PUT https://{tenancymoniker}.{domain}/HdaApi/rest/v2.0/WorkItems/{workItemId}/Versions/{VersionId}/CreateAndAssemble

Headers

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]

Parameters

Name	Type	Location	Required	Description
tenancymoniker	String	URL	Yes	The tenancy moniker for the tenancy in which you want to create the new work item.
workItemId	String	URL	Yes	The ID of the existing work item.
versionId	String	URL	Yes	A unique identified for the new version.

Examples

Example Request URL

PUT https://yourtenancy.yourorganization.com/HdaApi/rest/v2.0/WorkItems/{workItemId}/Versions/{VersionId}/CreateAndAssemble

Example Request JSON

{
  "templatePackageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "callbackUrl": "https://yourapp.com/api/callback",
  "callbackSecret": "mySecretKey"
}

Example Response

Status:

• 200 OK
• 202 Accepted