The goal for the Workfront API is to simplify building integrations with Workfront by introducing a REST-ful architecture that operates over HTTP. This document assumes you are familiar with REST and JSON responses and describes the approach taken by the Workfront API.

A familiarity with the Workfront schema will assist you in understanding the database relationships that can be utilized to pull data out of Workfront for integration purposes.

To ensure consistent Workfront on-demand system performance, each customer is limited to 10 concurrent API threads. The Sandbox environment has the same limit in place, allowing customers and partners to accurately test API calls before releasing code to production.

Disclaimer

Any use of the API should be tested in the Workfront beta environment prior to being run in the production environment. If any customer uses the API for a process that Workfront reasonably believes to be burdensome to the on-demand software (i.e., the process causes a materially negative effect on the performance of the software for other customers), Workfront reserves the right to request that the customer discontinues that process. If the customer does not comply and the problem persists, Workfront reserves the right to terminate the process.

REST Basics

This section provides a high-level introduction of how to interact with the Workfront REST API for the following REST principles:

Objects are manipulated by sending an HTTP request to their unique URI. The operation to be performed is specified by the HTTP method.

The standard HTTP methods correspond to the following operations:

GET - Retrieves an object by ID, searches for all objects by a query, runs reports, or executes named queries

POST - Inserts a new object

PUT - Edits an existing object

DELETE - Deletes an object

In order to work around client deficiencies or protocol length limits, the method parameter can be used to override HTTP behavior. For example, a GET operation may be implemented by posting the following URI:

GET /attask/api/v9.0/project?id=4c78...54d0&method=getGET /attask/api/v9.0/project/4c78...54d0?method=get

Response

Each request is given a response in JSON format. The response has either a data attribute if the request was successful or an error attribute if there was a problem. For example, the request

NOTE: When executing a GET request through your browser's address bar, it is not necessary to include the sessionID as part of the request.

Special security has been added around PUT, POST, and DELETE requests. Any request that results in writing to or deleting from the database can only be executed if the sessionID=abc123 is included in the URI. The following examples show how this would look for a DELETE request:

GET /attask/api/v9.0/project?id=4c78...54d0&method=delete&sessionID=abc123GET /attask/api/v9.0/project/4c78...54d0?method=delete&sessionID=abc123

Authentication

The API authenticates each request to ensure that the client has access to view or modify a requested object.

Authentication is performed by passing in a session ID which can be given using one the following methods:

The preferred method of authentication is to pass a request header named SessionID containing the session token. This has the advantage of being safe against Cross-site Request Forgery (CSRF) attacks and not interfering with the URI for caching purposes.

The following is an example of a request header:

GET /attask/api/v9.0/project/search SessionID: abc1234

Request Parameter Authentication

You can authenticate by passing a request parameter named sessionID, as shown in the following example:

GET /attask/api/v9.0/project/4c78821c0000d6fa8d5e52f07a1d54d0?sessionID=abc1234

Cookie-Based Authentication

The API uses the same cookie-based authentication that is used by the web UI to the system. Where, if a client logs into Workfront using the web UI, any AJAX calls made from within the same browser uses the same authentication.

Note: In order to protect against the possibility of CSS attacks, this method of authentication is only available for read-only operations.

Login

Using a valid username and password, you can use the following request to obtain a session ID:

POST /attask/api/v9.0/login?username=admin&password=user

This sets a cookie to authenticate future requests as well as return a JSON response with the newly created sessionID, the userID of the logged in user, and other session attributes.

NOTE If you have a designated API user who is also an administrator, Workfront strongly suggests you use an API Key to log in.

Generating an API Key

You can generate an API Key when you log into the system as that user, as shown in the following example:

You can then use this result to authenticate any API call by adding "apiKey" as a request parameter with this value in place of a sessionID or username and password. This is beneficial from a security perspective.

The following request is an example of retrieving data from a project using the apiKey:

If the apiKey value has been compromised, you can run "clearApiKey" which invalidates the current API Key, as shown in the following example:

GET /attask/api/v9.0/user?action=clearApiKey&username=user@email.com&password=userspassword&method=put

Once cleared, you can run getApiKey again to generate a new API Key.

Logout

When a session is complete, you can use the following request to log the user out, preventing any further access with the sessionID.

GET /attask/api/v9.0/logout?sessionID=abc1234

The sessionID to be logged out can be specified either as a cookie, request header, or request parameter.

To log out a user:

Navigate to your login screen, but do not log in.

Change the URL to /attask/api/v9.0/project/search.Notice the page cannot be found.

Replace the word search with login?username=admin&password=user, substituting your username and password for admin and userThis session is stored in the browser as a cookie and does not need to be restated in each subsequent GET request.

Change the URL back to /attask/api/v9.0/project/search.

Notice the response provided.

You must always include the sessionID provided after login when performing PUT, POST, and DELETE requests.

GET Behavior

Use the HTTP GET method to retrieve an object or multiple objects and to run reports.

Note: Search requests are case-sensitive. If you receive an error, ensure _Mod and _Range have the correct capitalization.

Using OR Statements

You can enhance a search by adding a parameter that includes "OR" as well as a number to indicate the level of a filter or series of filters.

An OR statement returns only records in the API call that meet the OR statement's filtering criteria. Filters are not implied across OR statement levels.

For example, if you want to filter for

Tasks that have a name containing "Planning" OR

Tasks in a portfolio named "FixedAssets" AND assigned to someone with a name containing "Steve" OR

Tasks that have a parent task named "Final Task"

then use the following API call with its multiple OR statements:

GET /attask/api/v9.0/task/search?name=Planning&name_Mod=contains&OR:1:portfolio:name=FixedAssets&OR:1:portfolio:name=eq&OR:1:assignedTo:name=Steve&OR:1:assignedTo:name_Mod=cicontains&OR:2:parent:name=Final Task&OR:2:parent:name_Mod=eq

Using Filter Parameters

One potential pitfall with using URL parameters for search filters is that Workfront parses certain parameters before checking for different authentication methods (i.e., username, password, apiKey, cookie). When this happens the parameters are not used as filters in the call.

To avoid this problem, you can place these values in filter parameters with JSON formatting. For example, if you want to filter for the username testuser, instead of using

/attask/api/v9.0/user/search?username=testuser@workfront.com

pass the URL parameter in a filter, as shown in the following example:

By default, the data returned from a search is a JSON array. Depending on your use case, it may be more efficient to get the result as a JSON object indexed by ID. This can be done by using the map request parameter. For example, the request

You can retrieve nested collections of objects. For example, to get a project with all its tasks, use the following request:

/attask/api/v9.0/project/search?fields=tasks

The following request gets task assignments:

/attask/api/v9.0/task/search?fields=assignments

Searching for Multiple Nested Fields

By default, only the name and ID of each task is returned, but additional nested fields can be specified with colon syntax. To view all available fields for a related object or collection, simply append a colon and asterisk to the object/collection reference.

/attask/api/v9.0/task/search?fields=assignments:*

Retrieving Custom Data

You can retrieve custom data fields using the prefix "DE:". For instance, to request a project with a parameter called "CustomText," use the following request:

Some object types have named searches that are commonly executed and are available by appending the name of the query to the end of the object type URI. For example, the following request retrieves the work items (tasks and issues) to which the user is currently assigned:

/attask/api/v9.0/work/myWork

Named queries support requesting the fields parameter to retrieve additional fields. Some named queries accept additional filters as well. For a list of allowable named queries an object, see the Action tab for the object in the API Explorer.

Using the Count Filter

You can specify the number of results you want to be returned by a given search. This allows the server to process the request more quickly and saves bandwidth. For example, the request

GET /attask/api/v9.0/project/count?status=CUR

returns the number of results in the following format:

{ "count": 3 }

This result is a much smaller download than if the full objects are sent. The filter syntax is identical to the search command.

Requesting a Report

You can perform a report request, where only the aggregate of some field is desired with one or more groupings. As shown in the following example, the report syntax is the same as the syntax for the SOAP API:

GET /attask/api/v9.0/hour/report?project:name_1_GroupBy=true&hours_AggFunc=sum

When querying an object, special consideration should be taken concerning the relationship of related objects and search limitations. For example, as shown in the following table, a query for projects can return no more than 2,000 projects. These 2,000 projects are considered "primary objects." If you query for the Tasks field on the projects, the Tasks field, which is a collection, becomes a secondary object to the primary object Project. A query for the Tasks field can include thousands of tasks on projects. In total, the combined number of objects (projects and tasks) returned cannot exceed the maximum of 50,000.

To ensure optimum performance the following table shows the limitations placed on search requests.

Query Result

Limitation

Description

Default Number of Results

100

If no limit is specified in the query filter (i.e., $$LIMIT), the result can contain no more than 100 primary objects. See "Using Paginated Responses" for instructions on how to override this limitation.

Max Number of Results

2,000

The query filter (i.e., $$LIMIT) can return no more than 2000 results. See "Paginated Responses" for more information.

Max Field Depth

4

When identifying the fields you wish to display, you cannot go more than four levels away from the object being queried.

Max Number of Objects

50,000

The result set cannot include 50000 primary and secondary objects.

Max Number of Fields

1,000,000

When the result set is fewer than 50000 objects, your results may include at most 1,000,000 fields.

Max Number of Batch Updates

100

The maximum batch update limit is 100.

Using Paginated Responses

To override the Default Number of Results query limitation and allow 200 results, you can include the $$LIMIT=200 filter in your query, as shown in the following example:

GET /attask/api/v9.0/project/search?$$LIMIT=200

In order to ensure reliability and performance for other tenants in the system, the maximum allowed results limit per query is 2000 objects. Attempting to specify a larger limit will result in an IllegalArgumentException error message.

Therefore, we recommend you consider using paginated responses for large datasets. To specify the first result that should be returned, add the $$FIRST filter. For example, the following request returns results 201-250 for a query:

GET /attask/api/v9.0/project/search?$$FIRST=201&$$LIMIT=50

Creating an Access Rule

You can create an access rule to determine who can access to an object. The following are examples of access rules you can set:

To set a project so it is shared only with a user with ID "abc123" use the following request:

Alternatively, to share only with a new person and keep existing permissions intact:

GET /attask/api/v9.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx/share?method=put&accessorID=abc123&accessorObjCode=USER&coreAction=VIEW

To retrieve the existing access rules:

GET /attask/api/v9.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?fields=accessRules:*

POST Behavior

POST inserts a new object. The syntax is identical to PUT, but with a few exceptions. Because the new object does not yet exist, it does not have an ID. For this reason, the URI does not include the ID.

The response includes the newly-created project along with its new ID and any other fields specified.

Copying an Object

Some objects support being copied. For these object types, it is possible to create new objects by posting with a copySourceID parameter. For example, the following request copies the given project and gives it a new name:

POST /attask/api/v9.0/project?copySourceID=4c7...&name=Copied Project

Uploading Documents

You can upload documents through the following API URL:

POST /attask/api/v9.0/upload

The API expects the content type to be multipart/form-data. The parameter name for the file must be uploadedFile. The server returns the following JSON data:

{ "handle": "4c7c08fa0000002ff924e298ee148df4"}

You can use the handle and post to the following URL when creating a Workfront document:

The response for a PUT is identical to a GET. In both cases, the server returns the new state of the object after the update. All rules used to alter a response to a GET request also work with PUT, such as specifying additional fields to be returned, custom data, and so on.

Editing Objects

Updates to objects are always done by ID using the object's unique URI. Fields to be updated are specified as request parameters. For instance, to change the name of a project you could send a request similar to the following:

NOTE While updates made to the top level are sparse, updates to a collection or nested object completely replace the existing collection. To edit a single assignment on a task without affecting the objects, use PUT on the assignment rather than on the task.

The following example makes a project a public help desk queue. Note that the existing queue properties are replaced.

Some objects support additional actions that can be performed in addition to simple edits. You can specify these actions using the action request parameter. For example, the following request recalculates the timeline for a given project:

PUT /attask/api/v9.0/project/4c7...?action=calculateTimeline

or

PUT /attask/api/v9.0/project/4c7.../calculateTimeline

Moving Objects

The following demonstrates the syntax for moving a task from one project to another:

PUT /attask/api/v9.0/task/4c7.../move?projectID=5d8...

An example for each action type is provided here: (??)

PUT /attask/api/v9.0/project/1234/approveApproval

PUT /attask/api/v9.0/project/1234/calculateFinance

PUT /attask/api/v9.0/project/1234/calculateTimeline

PUT /attask/api/v9.0/project/1234/calculateDataExtension

PUT /attask/api/v9.0/project/1234/recallApproval

PUT /attask/api/v9.0/project/1234/rejectApproval

PUT /attask/api/v9.0/task/1234/move

PUT /attask/api/v9.0/workitem/1234/markViewed

Only the move action requires identifying additional attributes to specify the project where the work item is to be moved.

The following example shows the syntax for moving a task from one project to another:

PUT /attask/api/v9.0/task/4c7.../move?projectID=5d8...

DELETE Behavior

DELETE removes an object. In every case, the URI may include the parameter force=true to cause the server to remove the specified data and its dependants. In the following example, a task is deleted by executing the HTTP DELETE method on a URI:

If you want all operations to happen in the same transaction, add “atomic=true” to your batch API call as a request parameter. This way, if any of the operations fail, all of the operations rolled back.

NOTE Atomic batch operations can only return “success: true” or an error.

Thank you for taking the time to provide feedback. We appreciate and value your contribution to our site. Feedback provided here is regularly reviewed by our Product Documentation team. Please ensure your comments are specific to improving this help article. Any questions or requests outside this help article content should be directed to our Community User Forum or by submitting a ticket to customer support.