Task API
Developing with the CLM API is only available for CLM customers with a production account. To purchase a plan to gain access to the CLM API, contact Docusign Sales.
The CLM Task API exposes Docusign CLM services as tasks that can be executed and monitored programmatically. It offers methods for generating documents, manipulating documents, advanced search, and other long-running document operations. JSON is the supported format for requests and responses.
Task API operations are based on a task object. However, the properties associated with the task object vary depending on the operation you are invoking. In general, you only need to include a subset of task properties to invoke a Task API method. See the API reference for details.
Using the Task API
Tasks are asynchronous, and are invoked and monitored in the following way:
-
To initiate a task operation, a POST request is made to a task endpoint. The request passes in a task object containing the subset of properties that the specific endpoint requires.
-
All POST requests to initiate a task will return a result object. The structure of the result object varies based on the task being invoked, but all result objects have some commonalities:
-
An
Hrefproperty that contains a URI that uniquely identifies the task invocation. You can make a GET request to this URI to check the status of the task and retrieve the results. For a longer-running task, you can periodically poll GET requests to this URI to check the current status and get the results of the task. -
A
Statusproperty that indicates the state or result of the operation. Statuses for most tasks include:Processing,Success, andFailure. Some tasks may also have specialized statuses. See the API reference for more information. -
Result properties that vary based on the task.
-
Some tasks allow you to cancel the operation. To cancel a task operation, make a DELETE request to the task URI.
Note: Although the Docusign CLM Advanced Workflow engine is a long-running series of tasks, it is not exposed via the Task API. The engine’s workflows, work items, and queues are considered objects and are exposed in the Object API.
Document search tasks
Example search request for “Contract” in the document name
Headers: Accept: 'application/json'
URI: https://apina11.springcm.com/v2/documentsearchtasks
Method: POST
JSON:
Example search response for “Contract” in the document name
Copy document tasks
Example request for Initiate Copy
Headers: Accept: 'application/json'
URI: https://apina11.springcm.com/v2/copytasks
Method: POST
JSON:
Example response for Initiate Copy
Example request for Check Status
Headers: Accept: 'application/json'
URI: https://apina11.springcm.com/v2/copytasks/95a91709-xxxx-xxxx-xxxx-11e18fd81b19
Method: GET
Example response for Check Status
Document generation tasks
Many task operations create a new document. For these tasks, you can handle the resulting document in one of the following ways:
- To save the document in CLM, specify a
DestinationFolderin your request object. - Alternatively, some tasks allow you to create a temporary file that you can download, without saving it in CLM. To do this, omit the
DestinationFolder. To determine which tasks allow you to create this temporary file, see the API reference.
The following examples of document generation tasks demonstrate the first option, in which you specify a DestinationFolder to save the resulting document in CLM.
Merging PDFs: Example request to Initiate Merge
Headers: Accept: 'application/json'
URI: https://apina11.springcm.com/v2/documentmergetasks
Method: POST
JSON:
Merging PDFs: Example response to Initiate Merge request
Merge Document Tasks - Check Status - Sample Request
Headers: Accept: 'application/json'
URI: https://apina11.springcm.com/v2/documentmergetasks/e4b9ddcf-xxxx-xxxx-xxxx-687fa2c2f6f1
Method: GET
Merge Document Tasks - Check Status - Sample Response
Next steps
See the API reference for a list of tasks and the methods you can use with them.