Adobe Workfront Planning API basics

The goal of the Adobe Workfront Planning API is to simplify building integrations with Planning by introducing a RESTful architecture that operates over HTTP. This document assumes you are familiar with REST and JSON responses.

For complete endpoint reference, request/ response schemas, and version-specific details, see the Workfront Planning API developer documentation.

Authentication

The Workfront Planning API uses OAuth 2.0 for authentication. Credentials are set up via the Adobe Developer Console.

We support the following two flows depending on your integration type:

To get started, create a project in the Adobe Developer Console and add the Workfront Planning API to obtain your credentials.

To set up credentials, create an OAuth2 application in Workfront.

For information, see Create OAuth2 applications for Workfront integrations.

API versioning

The Planning API is versioned via the URL path.

The following are current supported versions:

For more information about the current supported versions, see the article Workfront Planning API developer documentation.

We recommend explicitly targeting a version in all integrations:

https://{customer-domain}/maestro/api/v2/...

When a new major version is released, the previous version will continue to be available until a deprecation date is communicated.

Follow the Workfront release notes to stay informed of API changes.

URL structure and operations

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

For full endpoint paths and request/response examples, see the API reference at developer.adobe.com/wf-planning.

HTTP status codes

The Planning API returns standard HTTP status codes:

Error handling

The Planning API returns errors in a consistent format. Each error response includes a human-readable message, a machine-readable error code, and a request ID for support escalation.

Example error response:

json
{
  "title": "Validation failed",
  "status": 400,
  "detail": "Request validation failed. See 'errors' for details.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "req-123",
  "errors": [
    { "field": "name", "message": "must not be blank" }
  ]
}

Use errorCode (not status) to drive programmatic error handling. It provides the most specific classification of the failure.

Filtering records

Use the filter parameter in record search requests to return only records matching specific criteria. For POST requests, filter is a JSON property in the request body. For GET requests, filter is a query parameter containing a JSON-encoded filter group. Filters use a typed composite structure with explicit logical operators.

json
{
  "filter": {
    "operator": "AND",
    "conditions": [
      { "fieldId": "<fieldId>", "condition": "IS", "value": "Active" },
      { "fieldId": "<fieldId>", "condition": "CONTAINS", "value": "marketing" }
    ]
  }
}

Filters can be nested using AND / OR operators to build compound conditions:

json
{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "BETWEEN", "value": ["2024-03-31T20:00:00.000Z", "2024-04-01T20:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "IS_BETWEEN", "value": ["2024-04-15T00:00:00.000Z", "2024-04-16T00:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "planned" }
        ]
      }
    ]
  }
}

Field types and search modifiers

You can use modifiers and filters with fields to control what data will be returned in results.

For examples, see the Workfront Planning API developer documentation.

Using search modifiers

Workfront Planning supports the following search modifiers:

Supported filter conditions by field type

Filtering by People fields

People field filters (user, created-by, updated-by, approved-by) accept both Adobe IMS user IDs and Workfront user IDs. A plain string value is interpreted as an Adobe IMS user ID.

To set the identifier type to check the Workfront user ID, you need to explicitly pass id and idType parameters. Supported values for idType are “WF” for Workfront user IDs, and “IMS” for Adobe IMS user IDs.

{
  "filter": {
   "operator": "AND",
    "conditions": [
      {
        "fieldId": "<userFieldId>",
        "condition": "HAS_ANY_OF",
        "value": [
          { "id": "63e3b13000078c1795146248182d15dc", "idType": "WF" }
        ]
      }
    ]
  }
}

Filtering External Reference Fields by External ID

External reference fields link records to objects in other Adobe systems (such as Workfront projects or AEM Assets). Internally, Planning assigns Planning record IDs to these objects. To filter such fields directly by their original object ID, add "matchExternalId": true to a filter condition.

This flag is only valid for reference fields where referenceOptions.isExternal is true; it is ignored for non-external reference fields. If a single string value cannot be resolved, the request fails with 400 Bad Request. If a list value is supplied, unresolved entries pass through unchanged and simply do not match.

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {
        "fieldId": "<externalReferenceFieldId>",
        "condition": "IS_ANY_OF",
        "value": [
          "5f6a4f6e00000123456789abcdef0123",
          "/content/dam/wknd/en/adventures/bali-surf-camp"
        ],
        "matchExternalId": true
      }
    ]
  }
}

External connection fields

Planning record types can host external reference fields that link records to objects in other Adobe systems instead of other Planning record types.

To create an external reference field via the API, set referenceOptions.recordTypeId on a new REFERENCE field to the ID of the desired external record type. The server automatically derives referenceOptions.isExternal=true and the connection metadata (connectionName, objectName) from the target record type.

Supported external object types include Workfront objects (projects, tasks, programs, portfolios, companies, groups, teams, users) and AEM Assets (assets, content fragments).

Sorting

Sort results by any field by including a sort array in your request:

json
{
  "sort": [
    { "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" },
    { "fieldId": "F658afcbd4a0273c67c346fd5", "direction": "desc" }
  ]
}

Multiple sort fields are evaluated in order. Always apply a sort when paginating to ensure consistent ordering across pages.

To group results, include a group array alongside sort:

{
  "sort": [{ "fieldId": "F001", "direction": "asc" }],
  "group": [{ "fieldId": "F002", "direction": "asc" }]
}

Field projection

To limit which fields are returned in a response, use the fieldIds or fieldAliases query parameters with a comma-separated list. This reduces response payload size and is recommended for high-volume or latency-sensitive integrations.

Pagination

The Planning API supports paginated responses to manage large datasets.

For example, use the following request to retrieve the second page of 500 records from a record search:

POST /v2/record-types/{recordTypeId}/records/search?page=1&size=500
{
  "sort": [{ "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" }],
  "filter": { "operator": "AND", "conditions": [
    { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
  ] }
}

All paginated responses include a structured envelope indicating whether more results are available. Always apply a sort when paginating to ensure consistent ordering across pages.

Bulk operations

The Planning API supports bulk create, update, patch, and delete of records in a single request. Refer to the API reference at developer.adobe.com/wf-planning for endpoint paths, request formats, and per-operation record limits.

Permissions

Permissions to entities are managed through a dedicated Permissions API, separate from the resource endpoints themselves. This allows you to read current permissions, manage the sharing list, and handle access requests independently of data operations. For more information, see the “API references” section in the article Workfront Planning API.

Using the Planning API with Workfront custom forms

You can call the Planning API from an External lookup field in a Workfront custom form to surface Planning data directly within Workfront objects. For more information, see Examples of the External lookup field in a custom form.

Related resources

For more API-related documentation, also see the following articles: