Adding Images to a Document via the API

You can upload an image to a document using Advance's API methods. Using this method, you can also associate existing image values in Advance to which you have access permissions with your work item.

If you are displaying an interview, your end-users can use the image upload feature in Advance to upload images directly to the work item.


  • The template used for the work item must ask an Image variable.
  • Image variables are only supported in DOCX templates.
  • The default maximum file size for images is 10MB. You can edit this setting in the Core Assembly Service.
  • JPEG and PNG file formats are supported.

You cannot upload images to a completed version of a work item.

To upload an image value to a work item

  1. (If required) Create a new work item
  2. Begin an assembly session to create a new work item version. Pass in answer XML in the body of the request.
    Once you have uploaded the answer XML, Advance checks to find if any Image variables asked have existing image values in Advance to which the user has permissions. If any existing image values are found, Advance automatically associates the image reference to the work item version, avoiding the need to upload the image again.
  3. Advance sends an HTTP 200 response showing which image references have been found and which images you should upload.
  4. Using the list of image values required, upload each image:
    • Either: Pass the image to the active work item version: PUT /WorkItems/{workItemId}/Versions/active/Images/{imageReference}
    • Or: Pass the image to a specific work item version: PUT /WorkItems/{workItemId}/Versions/{versionId}/Images/{imageReference}
  5. Advance sends an HTTP 200 response to confirm the image has been uploaded.

Advance updates the image references on the work item version. When the document is assembled, the image values show as answered.