Adaptive Planning XML API Reference

Overview

VersionForge pushes data to Adaptive Planning through the XML API v40, specifically the importConfigurableModelData method. This endpoint accepts pipe-delimited row data embedded in an XML envelope and loads it into a target modeled sheet. Understanding this API is essential for debugging import failures and tuning batch performance.

Request Structure

Every import call is an XML POST to:

POST https://api.adaptiveplanning.com/api/v40
Content-Type: text/xml; charset=utf-8

The request body wraps your data in an XML envelope:

<?xml version='1.0' encoding='UTF-8'?>
<call method="importConfigurableModelData" callerName="VersionForge">
  <credentials token="your-api-token-here"/>
  <sheet name="Headcount Plan" isGlobal="false"
         isLevelAssigned="true" planOrActuals="Plan"
         replaceExisting="false"/>
  <rows>Account|Department|Amount
100|Engineering|50000
101|Sales|75000
102|Marketing|30000</rows>
</call>

Key XML Attributes

| Attribute | Description | |-----------|-------------| | method | Always importConfigurableModelData for data pushes. | | callerName | Identifies the calling application. VersionForge sets this to VersionForge. | | token | The API token from your credential configuration. | | name or sheetId | Target sheet identifier. Use one or the other. | | planOrActuals | Target version name (e.g., Plan, Actuals, Forecast Q2 2026). | | isLevelAssigned | Whether data is assigned to a specific level (true) or is global (false). | | replaceExisting | Set to true for replace mode. | | replaceAtLevel | For replace-at-level mode, specifies which level to scope the clear operation. |

Pipe-Delimited Payload Format

The <rows> element contains the data in pipe-delimited format. The first line is the header row with column names matching your Adaptive sheet columns. Subsequent lines are data rows.

Account|Department|Location|Period|Amount
4100|Engineering|San Francisco|Jan-26|120000
4200|Sales|New York|Jan-26|95000

Important formatting rules:

• Columns are separated by the pipe character (|)
• Pipes within field values are replaced with spaces -- Adaptive does not support escaping pipes
• XML special characters (&, <, >, ", ') in the rows content are XML-escaped in the envelope
• Empty values are represented as empty strings between pipes (e.g., 4100||San Francisco)
• Column order must match the header row exactly

Batch Sizing

VersionForge sends data in batches of 100 rows per API call. This batch size is chosen to balance throughput against Adaptive's per-request processing limits.

For a 5,000-row import, VersionForge issues 50 sequential API calls. Each call receives its own success/failure response, allowing VersionForge to track which batches succeeded and which need retry.

Error Response Handling

The Adaptive XML API returns success or failure at both the request level and the row level.

Request-Level Failure

If the entire request fails (invalid token, sheet not found, malformed XML), the response looks like:

<response success="false">
  <error>Invalid credentials</error>
</response>

VersionForge parses the success attribute and the error element to produce a descriptive pipeline error.

Row-Level Errors

When some rows are accepted and others rejected, Adaptive returns a mixed response. VersionForge maps row-level errors back to individual source records using the row index:

| Error Pattern | Likely Cause | |---|---| | "Unknown dimension value" | The value in a dimension column does not exist in Adaptive. Enable auto-create or add the dimension value manually. | | "Invalid account" | The account code in the data does not match any account in the target sheet's chart of accounts. | | "Duplicate key" | Two rows in the same batch have identical dimension combinations. Adaptive rejects the duplicate. | | "Period not found" | The period string does not match an active accounting period in the version. |

Metadata Discovery Endpoints

VersionForge uses several additional XML API methods to introspect the Adaptive model before pushing data:

| Method | Purpose | |--------|---------| | exportSheets | List all modeled sheets with IDs, names, and types | | exportSheetDefinition | Get column definitions for a specific sheet (name, type, required, dimension reference) | | exportDimensions | List all dimensions and their current member values | | exportLevels | Retrieve the level hierarchy for level-assigned sheets | | exportVersions | List available versions (plan/actuals) |

These discovery calls run automatically during the prepare() phase of each sync and are cached for the duration of the pipeline run.