Interactive API

Disclaimer: This is unofficial, community-created documentation for Epicor Prophet 21 APIs. It is not affiliated with, endorsed by, or supported by Epicor Software Corporation. All product names, trademarks, and registered trademarks are property of their respective owners. Use at your own risk.

Original source: much of this document's verified material — the response-window and popup mechanics, the in-window wizard, the ui/full surface — originates in Alex Westemeier's process work, re-verified here before publication. Section-level credits appear throughout.

Overview

The Interactive API (IAPI) is a stateful RESTful API that simulates user interaction with P21 windows. It maintains session state, allowing you to perform complex multi-step operations with full business logic validation.

Key Characteristics

• Stateful - Maintains session like a real user
• Full business logic - All validations applied
• Window-based - Works with P21 windows and fields
• Response window handling - Can handle dialogs
• Complex workflows - Multi-step operations supported

When to Use

• Complex data entry requiring business logic
• Multi-step workflows with dependencies
• Operations that trigger response windows
• When you need to interact like a real user

Endpoints

All Interactive API endpoints use the UI Server URL. First, obtain it:

GET https://{hostname}/api/ui/router/v1/?urlType=external

Then use the returned URL as base:

Session Management

Window Operations (v2)

Data Operations (v2, Recommended)

Important: Some P21 servers only support v2 endpoints. If you receive 404 errors on v1 endpoints, use v2 instead.

Query Parameter Inconsistency: Most v2 endpoints use ?id= for the window identifier, but the tools endpoint uses ?windowId=. Verified by live testing:

Endpoint	Accepts ?id=	Accepts ?windowId=
GET/DELETE /v2/window	Yes	No (422)
GET/DELETE /v2/data	Yes	No (400/422)
GET /v2/tools	No (400)	Yes

Using the wrong parameter returns an error — there is no fallback. GET /v2/tools?id= fails with HTTP 400 and a validation body ("The windowId field is required.").

Data Operations (v1 - Legacy)

Authentication

Include the Bearer token in the Authorization header:

POST /api/ui/interactive/sessions HTTP/1.1
Host: {ui-server-host}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json

See Authentication for token generation.

Session Lifecycle

1. Start Session

POST /api/ui/interactive/sessions
{
    "ResponseWindowHandlingEnabled": false
}

Response (25.2):

{
    "SessionId": "abc123...",
    "Status": "Active"
}

Response (2026.1 — the identifier is renamed SessionId → Id):

{
    "Id": "3f2b8c9e-1234-4a5b-9c0d-7e8f9a0b1c2d",
    "Properties": [
        {
            "Name": "Telemetry",
            "Properties": {
                "fullversion": "26.1.5894.1",
                "shortversion": "26.1",
                "configurationid": "3694"
            }
        }
    ]
}

Read both keys — data.get("Id") or data.get("SessionId") — so one client works across versions. See Breaking Changes § 2026.1.

This is also how you find your middleware build. P21 exposes no version endpoint (/api/version, /api/v2/version and similar all return 404). On 2026.1 the session-create response carries it under Properties[0].Properties.fullversion — the most reliable way to confirm which build you're talking to before relying on any version-specific behavior.

Session Parameters (UserParameters)

The session creation body accepts these optional parameters:

Example with multiple parameters:

POST /api/ui/interactive/sessions
{
    "SessionType": "Auto",
    "SessionTimeout": 120,
    "ResponseWindowHandlingEnabled": false,
    "ClientPlatformApp": "PricePageSync",
    "WorkstationID": "INTEGRATION-01"
}

Session pool limits: The server has a finite pool of API instances (default: 5). If all instances are busy, new session requests will wait up to 60 seconds before timing out. See Session Pool Troubleshooting for configuration details and common issues.

2. Open Window

There are four ways to identify which window to open:

POST /api/ui/interactive/v2/window
{
    "ServiceName": "SalesPricePage"
}

Or by menu title:

{
    "Title": "Sales Price Page Entry"
}

Response:

{
    "WindowId": "3f2b8c9e-1234-4a5b-9c0d-7e8f9a0b1c2d",
    "Title": "Sales Price Page Entry",
    "DataElements": [...]
}

Use ServiceName — the by-Name and by-Title paths are unreliable. On 26.1 (verified 26.1.5894.1, July 2026), opening by Name or Title can be rejected with HTTP 400 even for a window whose ServiceName opens fine:

text {"ServiceName": "Territory"} -> 200, window opens {"Name": "w_territory_maint"} -> 400 "Cannot open window w_territory_maint because is not available or user <API_USER> does not have permission." {"Title": "Postal Code Group Maintenance"} -> 400 (the window name resolves to empty in the error text)

Despite the "not available or user does not have permission" wording, this is the same undeployed/unavailable-window signal seen on the Transaction API — a window is only reliably API-openable through a registered service name. Discover the service name for a window via frame_menu.service_name (see Window→Service Discovery). Prefer ServiceName for every open.

Read the window name in the error — the blank is the diagnostic. The message interpolates whatever name the middleware resolved, so an empty name means the identifier you sent resolved to nothing in the service registry, while an echoed name means it resolved and the window was refused. {"ServiceName": "SupplierGroup"} on a service that does not exist returns Cannot open window because is not available... with two spaces where the name belongs; {"Name": "w_supplier_group_maint"} on the same window echoes the name back. A blank is your cue to check frame_menu for a NULL service_name and, if the window is web-enabled, to reach for the ui/full surface instead (verified 26.1.5940.0, August 2026).

3. Change Data

v2 Format (Recommended):

PUT /api/ui/interactive/v2/change
{
    "WindowId": "3f2b8c9e-1234-4a5b-9c0d-7e8f9a0b1c2d",
    "List": [
        {
            "TabName": "FORM",
            "FieldName": "description",
            "Value": "New Description",
            "DatawindowName": "form"
        }
    ]
}

Note: v2 uses List with TabName, while v1 uses ChangeRequests with DataWindowName. The DatawindowName field in v2 uses lowercase 'w'.

P21 25.2+ Breaking Change: DatawindowName is now effectively required for v2 change requests. The 3-parameter form (TabName + FieldName + Value) stopped working after the 25.2 upgrade — you must include DatawindowName as the 4th field. Window data structures changed in 25.2 so the server can no longer auto-resolve the target datawindow from TabName alone. Always include DatawindowName in change requests.

Affected windows (confirmed):

Window	Affected Field	Reporter
Item	Various	Community reports
PO Receiving Group	po_criteria_id on Criteria tab	Jeff Patterson, Josiah Shollenberger
Delivery List	Various	Community reports
Group Pick Ticket	Various	Community reports
ConvertPOToVoucher	po_no on Voucher Information tab	Jeff Patterson, Josiah Shollenberger
Order Entry	order_no on Order tab	Neil Timmerman
Clippership Auto Shipping	pick_ticket_no	Josh Owen
Doc Links	Various	Jaime Nelson

The bug persists through at least version 25.2.5776.1. Epicor has acknowledged this as a development bug.

Fix example (C# SDK) — the P21 C# SDK's ChangeData, not the REST call. For the REST equivalent see the change payloads in Linking Price Page to Price Book.

// Broken in 25.2+:
porgwindow.ChangeData("Criteria", "po_criteria_id", "20");

// Fixed — include DatawindowName:
porgwindow.ChangeData("Criteria", "tp_1_dw_1", "po_criteria_id", "20");

Credit: David Sokoloski (first discovered 4-param workaround), Jeff Patterson (confirmed fix)

ValueType

Each change request supports an optional ValueType field:

{
    "TabName": "FORM",
    "DatawindowName": "form",
    "FieldName": "supplier_id",
    "Value": "10050",
    "ValueType": "Data"
}

Most of the time you can omit ValueType — the default Display works for typical field changes. Use Data when you need to set a field by its internal key value rather than its display text.

v1 Format (Legacy):

PUT /api/ui/interactive/v1/change
{
    "WindowId": "w_sales_price_page",
    "ChangeRequests": [
        {
            "DataWindowName": "d_form",
            "FieldName": "description",
            "Value": "New Description"
        }
    ]
}

4. Save Data

v2 Format (Recommended):

PUT /api/ui/interactive/v2/data
"3f2b8c9e-1234-4a5b-9c0d-7e8f9a0b1c2d"

Critical: In v2, send just the WindowId GUID string as the JSON body - NOT wrapped in an object. This is a common source of 422 errors.

v1 Format (Legacy):

PUT /api/ui/interactive/v1/data
{
    "WindowId": "w_sales_price_page"
}

5. Close Window

DELETE /api/ui/interactive/v2/window?id=w_sales_price_page

6. End Session

DELETE /api/ui/interactive/sessions

No body, no query parameter. The endpoint deletes the session belonging to the bearer token you send — which is why it needs neither.

A session can only be deleted by the token that created it. Verified on 26.1.5910.3 (2026-08-11) and re-verified on 26.1.5950.0 (2026-09-11): create a session and DELETE it on the same token and you get 200 and the session is gone. Present a different token — a fresh login after your process restarted, another worker, a retry that re-authenticated — and every form is refused with 400 {"ErrorMessage":"Invalid session"}:

Attempt (different token)	Result
DELETE /sessions (no body, as documented)	400 Invalid session
DELETE /sessions?id={sessionId}	400 Invalid session
DELETE /sessions?sessionId={sessionId}	400 Invalid session
DELETE /sessions body {"Id": "..."}	400 Invalid session
DELETE /sessions body {"SessionId": "..."}	400 Invalid session
DELETE /v2/sessions?id={sessionId}	404 (no such endpoint)

The orphan stays visible in GET /api/ui/interactive/sessions — the listing is scoped to the user, not the token, so a second token for the same login sees the session it cannot delete — and there is no documented way to reap it early: you wait out SessionCleanupExpiration. The practical rule: delete the session on the token that opened it, in a finally, before that token goes out of scope. Once the token is gone, so is your ability to clean up.

Finding Field Names

To find the correct field and datawindow names:

1. Open P21 in the web client
2. Navigate to the window
3. Right-click on the field
4. Select Help > SQL Information
5. Note the datawindow name and column name

Window Discovery Techniques

Source: Community working code + actual API testing (April 2026). Credit: Jon Christie.

Understanding a window's structure is essential before automating it. These techniques help you discover datawindow names, field names, available tools, and current data.

1. Get Window State

After opening a window, call GetState() (SDK) or GET /api/ui/interactive/v2/window?id={windowId} (REST) to retrieve the window definition — datawindows, fields, tabs, enabled states, and current data.

The response shape, verified live on 26.1.5910.3 (2026-08-11):

{
  "Data": { /* current values */ },
  "Definition": {
    "Id": "...", "Name": "...", "Title": "...",
    "TabPageList": [ /* array */ ],
    "Datawindows": {                 // a MAP keyed by datawindow name -- not an array
      "tp_1_dw_1": {
        "Name": "...", "ParentPage": "...", "Style": "...",
        "Fields": { /* also a MAP, keyed by field name */ }
      },
      "tp_17_dw_17": { }
    }
  }
}

Three things that catch people out:

• Everything is under Definition. The datawindows are not at the top level; Data is a sibling, not a parent.
• Datawindows and Fields are maps, not arrays. Iterating them positionally yields keys (strings), not objects. TabPageList is an array — the two shapes sit side by side.
• You get the ACTIVE tab page's datawindows, not the whole window. This is the part that misleads people into thinking a field doesn't exist. Verified on SalesPricePage (26.1.5910.3) by selecting each tab and re-reading:

Each selection replaces the previous one. So a datawindow's absence proves only that its tab isn't active — switch tabs with PUT /v2/tab (PageName) and read again, or use definitions/{Service}.json for the whole picture at once. The same caveat applies to GET /v2/data.

• Interactive datawindow names are not the Transaction API's names. The same tab is form here and d_dw_price_page_main in definitions/SalesPricePage.json; values vs d_dw_price_page_values; costs vs d_dw_price_page_cost. Both are correct — for their own API. Sending a d_dw_* name in an Interactive DatawindowName, or a short name in a Transaction DataElement, will not find the datawindow. The tab page names (FORM, VALUES, COSTS, PO COST MULTIPLIERS, USED BY, TP_PRICE_PAGE_X_LOCATION, TIMESTAMPPRICE_PAGE) are shared, and come back in Definition.TabPageList with their display text and Enabled state.

• Field metadata here carries no dropdown values. Each field exposes only Name, Label, DataType and Enabled — there is no ValidValues. To learn what a code field accepts, read the Transaction definition (GET /api/v2/definition/{Service}) even when you intend to drive the window interactively; it lists the display labels you send under UseCodeValues: false. See SalesPricePage Codes.

Complete program — authenticates, opens a window by ServiceName, prints every tab and datawindow it exposes, then closes the window and the session. Run it against any window whose structure you need before automating it.

"""Open a P21 window and print the tabs, datawindows and fields it exposes."""
import re

import httpx

# ---- EDIT THESE -----------------------------------------------------------
BASE_URL = "https://play.p21server.com"   # your P21 server
USERNAME = "apiuser"
PASSWORD = "your-password"
VERIFY_SSL = False                        # True once you trust the cert chain
SERVICE_NAME = "SalesPricePage"           # window to inspect — always open by ServiceName
# ---------------------------------------------------------------------------


def get_token(client: httpx.Client) -> str:
    """v2 token endpoint — credentials go in the body, never in headers."""
    r = client.post(
        f"{BASE_URL}/api/security/token/v2",
        json={"username": USERNAME, "password": PASSWORD},
        headers={"Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["AccessToken"]
    except (ValueError, KeyError):  # some middleware answers in XML
        match = re.search(r"<AccessToken>([^<]+)</AccessToken>", r.text)
        if not match:
            raise ValueError(f"No AccessToken in response: {r.text[:200]}") from None
        return match.group(1)


def get_ui_server(client: httpx.Client, token: str) -> str:
    """Transaction and Interactive calls go to the UI server, not BASE_URL."""
    r = client.get(
        f"{BASE_URL}/api/ui/router/v1/?urlType=external",  # trailing slash avoids a 307
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["Url"].rstrip("/")
    except (ValueError, KeyError):
        match = re.search(r"<Url>([^<]+)</Url>", r.text)
        if not match:
            raise ValueError(f"No Url in router response: {r.text[:200]}") from None
        return match.group(1).rstrip("/")


with httpx.Client(verify=VERIFY_SSL, timeout=120, follow_redirects=True) as client:
    token = get_token(client)
    ui_server = get_ui_server(client, token)
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",       # without this you get XML, not JSON
        "Content-Type": "application/json",
    }

    r = client.post(
        f"{ui_server}/api/ui/interactive/sessions",
        headers=headers,
        json={"ResponseWindowHandlingEnabled": False},
    )
    r.raise_for_status()
    session = r.json()
    # 25.2 returns SessionId; 2026.1 renamed it Id — read either.
    print("session:", session.get("Id") or session.get("SessionId"))

    window_id = None
    try:
        r = client.post(
            f"{ui_server}/api/ui/interactive/v2/window",
            headers=headers,
            json={"ServiceName": SERVICE_NAME},
        )
        r.raise_for_status()
        opened = r.json()
        window_id = opened.get("WindowId") or opened.get("Id")
        print("window:", window_id)

        r = client.get(
            f"{ui_server}/api/ui/interactive/v2/window",   # note: ?id=, not ?windowId=
            headers=headers,
            params={"id": window_id},
        )
        r.raise_for_status()
        state = r.json()
        definition = state.get("Definition", state)

        for tab in definition.get("TabPageList", []):
            print(f"tab {tab.get('Name')!r:32} enabled={tab.get('Enabled')}")

        # Datawindows arrive as a map keyed by name; normalise to a list either way.
        datawindows = definition.get("Datawindows", {})
        if isinstance(datawindows, dict):
            datawindows = [{"Name": k, **v} for k, v in datawindows.items()]
        for dw in datawindows:
            fields = dw.get("Fields", {})
            names = sorted(fields) if isinstance(fields, dict) else [
                f.get("Name") for f in fields
            ]
            print(f"datawindow {dw.get('Name')} (tab: {dw.get('ParentPage')})")
            print(f"    fields: {names}")
    finally:
        if window_id:
            client.delete(
                f"{ui_server}/api/ui/interactive/v2/window",
                headers=headers,
                params={"id": window_id},
            )
        # Always delete the session: a leaked one 409s ("Session already exists")
        # on your next create until it is cleaned up.
        client.delete(f"{ui_server}/api/ui/interactive/sessions", headers=headers)

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// ---- EDIT THESE -----------------------------------------------------------
const string BaseUrl = "https://play.p21server.com";   // your P21 server
const string Username = "apiuser";
const string Password = "your-password";
const string ServiceName = "SalesPricePage";           // window to inspect — open by ServiceName
// ---------------------------------------------------------------------------

var handler = new HttpClientHandler
{
    // Test tenants often present a self-signed cert. Delete this line in production.
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(2) };
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var token = await GetTokenAsync(client);
var uiServer = await GetUiServerAsync(client, token);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var sessionResponse = await client.PostAsync(
    $"{uiServer}/api/ui/interactive/sessions",
    Json(new { ResponseWindowHandlingEnabled = false }));
sessionResponse.EnsureSuccessStatusCode();
using (var session = JsonDocument.Parse(await sessionResponse.Content.ReadAsStringAsync()))
{
    // 25.2 returns SessionId; 2026.1 renamed it Id — read either.
    Console.WriteLine($"session: {Field(session.RootElement, "Id") ?? Field(session.RootElement, "SessionId")}");
}

string? windowId = null;
try
{
    var openResponse = await client.PostAsync(
        $"{uiServer}/api/ui/interactive/v2/window",
        Json(new { ServiceName }));
    openResponse.EnsureSuccessStatusCode();
    using (var opened = JsonDocument.Parse(await openResponse.Content.ReadAsStringAsync()))
        windowId = Field(opened.RootElement, "WindowId") ?? Field(opened.RootElement, "Id");
    Console.WriteLine($"window: {windowId}");

    // note: ?id=, not ?windowId=
    var stateResponse = await client.GetAsync(
        $"{uiServer}/api/ui/interactive/v2/window?id={windowId}");
    stateResponse.EnsureSuccessStatusCode();

    using var state = JsonDocument.Parse(await stateResponse.Content.ReadAsStringAsync());
    var definition = state.RootElement.TryGetProperty("Definition", out var d)
        ? d
        : state.RootElement;

    if (definition.TryGetProperty("TabPageList", out var tabs))
        foreach (var tab in tabs.EnumerateArray())
            Console.WriteLine($"tab {Field(tab, "Name")} enabled={Field(tab, "Enabled")}");

    if (definition.TryGetProperty("Datawindows", out var datawindows))
    {
        // Datawindows arrive as a map keyed by name; tolerate an array too.
        var entries = datawindows.ValueKind == JsonValueKind.Object
            ? datawindows.EnumerateObject().Select(p => (Name: p.Name, Value: p.Value))
            : datawindows.EnumerateArray().Select(e => (Name: Field(e, "Name") ?? "", Value: e));

        foreach (var (name, dw) in entries)
        {
            var fields = new List<string>();
            if (dw.TryGetProperty("Fields", out var f))
                fields = f.ValueKind == JsonValueKind.Object
                    ? f.EnumerateObject().Select(p => p.Name).ToList()
                    : f.EnumerateArray().Select(e => Field(e, "Name") ?? "").ToList();

            Console.WriteLine($"datawindow {name} (tab: {Field(dw, "ParentPage")})");
            Console.WriteLine($"    fields: {string.Join(", ", fields)}");
        }
    }
}
finally
{
    if (windowId is not null)
        await client.DeleteAsync($"{uiServer}/api/ui/interactive/v2/window?id={windowId}");

    // Always delete the session: a leaked one 409s ("Session already exists")
    // on your next create until it is cleaned up.
    await client.DeleteAsync($"{uiServer}/api/ui/interactive/sessions");
}

// --- helpers ---------------------------------------------------------------

static StringContent Json(object body) =>
    new(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");

static string? Field(JsonElement element, string name) =>
    element.TryGetProperty(name, out var value) ? value.ToString() : null;

// v2 token endpoint — credentials go in the body, never in headers.
static async Task<string> GetTokenAsync(HttpClient client)
{
    var payload = JsonSerializer.Serialize(new { username = Username, password = Password });
    var response = await client.PostAsync(
        $"{BaseUrl}/api/security/token/v2",
        new StringContent(payload, Encoding.UTF8, "application/json"));
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "AccessToken");
}

// Transaction and Interactive calls go to the UI server, not BaseUrl.
static async Task<string> GetUiServerAsync(HttpClient client, string token)
{
    using var request = new HttpRequestMessage(
        HttpMethod.Get, $"{BaseUrl}/api/ui/router/v1/?urlType=external");
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var response = await client.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "Url").TrimEnd('/');
}

// Some middleware answers these two endpoints in XML even when asked for JSON.
static string ReadField(string payload, string field)
{
    try
    {
        var value = JsonDocument.Parse(payload).RootElement.GetProperty(field).GetString();
        if (!string.IsNullOrEmpty(value)) return value;
    }
    catch (Exception ex) when (ex is JsonException or KeyNotFoundException) { }

    var match = System.Text.RegularExpressions.Regex.Match(payload, $"<{field}>([^<]+)</{field}>");
    if (!match.Success)
        throw new InvalidOperationException(
            $"No {field} in response: {payload[..Math.Min(200, payload.Length)]}");
    return match.Groups[1].Value;
}

Example response (sanitized, structure varies by window):

{
  "Definition": {
    "Title": "Order Entry",
    "Datawindows": {
      "form": {
        "Fields": {
          "order_no": {"Label": "Order No", "Enabled": true, "DataType": 1},
          "customer_id": {"Label": "Customer ID", "Enabled": true, "DataType": 1}
        }
      }
    },
    "TabPageList": [
      {"Name": "Order", "DisplayText": "Order"},
      {"Name": "Line_Items", "DisplayText": "Line Items"}
    ]
  }
}

Tip: Response windows return an empty TabPageList — that is how you can distinguish them from normal windows programmatically.

2. Get Available Tools

Call GetTools() (SDK) or GET /api/ui/interactive/v2/tools?windowId={windowId} (REST) to see available buttons. Tools can be queried at window, datawindow, and field levels by adding dwName, fieldName, and row parameters.

Example response:

[
  {"ToolName": "cb_ok", "DatawindowName": null, "FieldName": null},
  {"ToolName": "cb_cancel", "DatawindowName": null, "FieldName": null},
  {"ToolName": "m_addlink", "DatawindowName": "Document_Link", "FieldName": null}
]

3. Get Current Data

Call GetData() (SDK) or GET /api/ui/interactive/v2/data?id={windowId} (REST) to retrieve the current data in each datawindow on the active tab. Returns column names, row data, active row index, and total row count.

4. Check Result Events

Every API response includes an Events collection. When a response window opens, look for Name: "windowopened" events. When tabs become enabled, look for Name: "tabpageenabled" events. When a new record is saved, look for Name: "keygenerated" events.

5. P21 SQL Information

In the P21 desktop or web client, right-click any field and select Help > SQL Information. This dialog shows: - Datawindow name — the name to use in DatawindowName for change requests - Column name — the field name to use in FieldName - Table name — the underlying database table

This is the most reliable way to determine the exact names the API expects.

6. Browser DevTools

When using the P21 Web Client, open your browser's Developer Tools (F12) and watch the Network tab. Every action you perform in the UI generates REST calls to the Interactive API. This lets you see the exact payloads, endpoints, and field names the web client uses — which you can replicate in your automation.

7. Transaction API Service Definition

For windows that also exist as Transaction API services (Order, PurchaseOrder, Item, etc.), GET /api/v2/definition/{ServiceName} returns the full schema: every DataElement with its DatawindowName, Type (Form/List), KeyFields, and FieldDefinitions[] (field Name, DbColumnName, DataType, Required). This is the fastest way to enumerate which datawindows exist and which column names a write needs. See Get Service Definition in the Transaction API guide.

Warning — don't derive TABPAGE_N from the visible tab order: The TABPAGE_N names are not sequential with the tabs you see in the UI. The PurchaseOrder window, for example, has 37 tab pages — many disabled or hidden, split across the header and detail bands — so the Items grid that looks like the second tab is actually TABPAGE_17 (tp_17_dw_17). Counting visible tabs gives you the wrong name. Read the TabPageList from the window state (GET /api/ui/interactive/v2/window?id={windowId}) or cross-reference on the datawindow name (tp_N_dw_N / d_...). On the servers tested (25.2/26.x), the Interactive window's TABPAGE_N names matched the Transaction API definition's 1:1 — the datawindow name remains the safest identifier either way.

8. Window-to-Service Discovery (frame_menu)

Because opening by Name/Title is unreliable and only a registered service name reliably opens a window, you need a way to map a menu item / w_* window to its service name. The Prophet21.dbo.frame_menu table is that map:

SELECT menu_item_name,      -- the menu label ("Territory Maintenance")
       stringparm,          -- the w_* window name ("w_territory_maint")
       class_name,          -- the m_* menu class ("m_territorymaintenance") — the ui/full route
       service_name,        -- the ServiceName ("Territory") — NULL = no Transaction/Interactive surface
       enabled,             -- menu item enabled
       new_ui_enabled,      -- available in the new (web) UI
       angular_enabled      -- available in the Angular client
FROM   frame_menu
WHERE  stringparm LIKE 'w[_]%';

• service_name is the identifier to pass as ServiceName — e.g. Territory Maintenance → Territory, Territory Group Maintenance → TerritoryGroup.
• service_name IS NULL marks a window with no Transaction or Interactive surface — it 500s on GET /api/v2/definition/{guess} and 400s on an Interactive by-Name open. It does not mean the window is unreachable: a NULL-service window that the web client can open is still drivable through the ui/full surface by its menu class name. Read the two columns together — service_name NULL and new_ui_enabled/angular_enabled 'N' is the combination that means no API can reach it. On the tested 26.1 system, Zip Code Maintenance (w_zip_code_maint) and Postal Code Group Maintenance (w_postal_code_group_maint) are both NULL and web-disabled — classic-desktop-only, undeployed windows, refused on ui/full as well (see Undeployed/unavailable windows). Supplier Group Maintenance (w_supplier_group_maint) is the other case: NULL service name, web-enabled, and it opens on ui/full.
• class_name is the column you need for that fallback — the m_* menu class the ui/full surface opens windows by. Select it alongside service_name and you get both routes out of one query.
• This complements the window_x_menu discovery path documented for report (m_*) services: window_x_menu finds callable report names; frame_menu.service_name finds the interactive/transaction service name behind a maintenance window.

Environment: verified on 26.1.5894.1 (play), July 2026. (The "does not have permission" wording names whichever user is calling — it's an availability signal, not a grantable permission.)

Response Windows

Response windows (dialogs) can pop up during operations. When this happens:

1. The result will have Status: 3 (Blocked)
2. Check the Events array for windowopened
3. Get the new window ID from the event data
4. Handle the response window (interact with it like any other window)
5. Close/dismiss it to resume the original operation

The popup's id lives in Events — not in the top-level ResponseWindowId. That field exists in the response and is empty on real 26.1 responses, so a client that reads it gets "" and concludes there is no popup to answer. A production integration had every blocked save fail this way before switching to the event. Read Events[] → windowopened → Data[] → windowid; check the top-level field first only as forward-compatibility, never as the primary source.

There is no dedicated "answer this dialog" endpoint. Probed and dead (January 2026): PUT /api/ui/interactive/v2/responsewindow → 404, PUT /api/ui/interactive/v2/responsewindows → 404, POST /api/ui/interactive/v2/button → 404, DELETE /api/ui/interactive/v2/window?button=No → 400. Answer any response window, w_message included, through the general mechanism instead: discover buttons via GET /tools?windowId={id}, click one via POST /tools (see Response Window Types, worked example). This requires ResponseWindowHandlingEnabled: true. With false, a w_message is auto-answered with its default (usually "Yes") before it becomes a window you can query at all — e.g. changing product_group_id on inv_loc triggers a "update GL accounts?" dialog whose default overwrites the location's GL, revenue, and COS accounts. The answer given is echoed in the response's Messages array as "<question text> [Response: Yes]".

Status codes match the ResultStatus enum in P21.UI.Service.Model.Interactive.V2.ResultWrapper: None=0, Success=1, Failure=2, Blocked=3. The API returns Status as an integer. String values ("Success", "Failure", "Blocked") may appear in some contexts — handle both.

Example response with blocked status:

{
    "Status": 3,
    "Events": [
        {
            "Name": "windowopened",
            "Data": [
                { "Key": "windowid", "Value": "w_response_123" }
            ]
        }
    ]
}

Note: The Events[].Data field uses a key-value list format: [{"Key": "windowid", "Value": "..."}]

Response Window Handling (Tabless Windows)

Response windows (popup dialogs) have no tabs. When you receive Status: 3 (Blocked), a response window has appeared and you must interact with it before continuing. The critical difference from normal windows is that change requests on response windows require TabName = null because there are no tabs to reference.

REST API pattern:

Include "TabName": null in the change request payload:

PUT /api/ui/interactive/v2/change
{
    "WindowId": "w_response_123",
    "List": [
        {
            "TabName": null,
            "DatawindowName": "datawindow_name",
            "FieldName": "field_name",
            "Value": "value"
        }
    ]
}

REST examples (Python / C#) — one step of a longer sequence: the response window must already have been opened by something (a tool, a save), and its ID comes from that call's windowopened event.

Full runnable version: Recipe: Add a Header Note

async def change_response_window_field(
    client: httpx.AsyncClient,
    ui_url: str,
    headers: dict[str, str],
    response_window_id: str,
    datawindow_name: str,
    field_name: str,
    value: str,
) -> dict:
    """Change a field on a tabless response window.

    Args:
        client: httpx async client.
        ui_url: UI server base URL.
        headers: Request headers with auth token.
        response_window_id: The response window ID from the windowopened event.
        datawindow_name: Datawindow name within the response window.
        field_name: Field to change.
        value: New value.

    Returns:
        Parsed response dict.
    """
    response = await client.put(
        f"{ui_url}/api/ui/interactive/v2/change",
        headers=headers,
        json={
            "WindowId": response_window_id,
            "List": [
                {
                    "TabName": None,
                    "DatawindowName": datawindow_name,
                    "FieldName": field_name,
                    "Value": value,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()

public async Task<JsonElement> ChangeResponseWindowFieldAsync(
    HttpClient http,
    string uiUrl,
    string responseWindowId,
    string datawindowName,
    string fieldName,
    string value)
{
    // Response windows have no tabs — set TabName to null
    var payload = new JsonElement
    {
        ["WindowId"] = responseWindowId,
        ["List"] = new JsonElement
        {
            new JsonElement
            {
                ["TabName"] = null,
                ["DatawindowName"] = datawindowName,
                ["FieldName"] = fieldName,
                ["Value"] = value
            }
        }
    };
    var content = new StringContent(payload.ToString(), Encoding.UTF8, "application/json");
    var response = await http.PutAsync($"{uiUrl}/api/ui/interactive/v2/change", content);
    response.EnsureSuccessStatusCode();

    return JsonElement.Parse(await response.Content.ReadAsStringAsync());
}

Note: The TabName: null pattern applies to response windows that accept change requests (editable dialogs with Status: 3/Blocked). w_message dialogs have no fields — GET /window?id={popupId} returns an empty Datawindows/TabPageList, only a Title — so dismiss them with POST /tools instead (see the worked example below). Use ResponseWindowHandlingEnabled: false only when the default answer is acceptable unconfirmed — the GL-account prompt's default overwrites GL/revenue/COS accounts.

Common response window buttons: cb_ok, cb_cancel, cb_finish, cb_yes, cb_no

Use GET /api/ui/interactive/v2/tools?windowId={responseWindowId} to discover which buttons are available, then POST /api/ui/interactive/v2/tools to click them. See the Response Window Types section below for dismissal patterns.

Credit: Jon Christie

Worked Example: "Item Issues Detected" (rule callback)

A concrete w_rule_callback_response case from the Item window. Items with data problems pop an "Item Issues Detected" dialog; the Transaction API cannot get past it (the change is discarded — see Item Service gotchas). Interactively, it's answerable:

1. Start the session with ResponseWindowHandlingEnabled: true.
2. Open the Item window and set item_id on TABPAGE_1.tp_1_dw_1. Some items pop the dialog at retrieve time — the moment item_id is set — which blocks the location list from loading. Check the result for a windowopened event and answer the popup immediately, not just at save.
3. Navigate and make your edits (e.g. select the location row on TABPAGE_17.invloclist, edit TABPAGE_18.inv_loc_detail).
4. save() — if the dialog opens, the result is Status 3 (Blocked) with a windowopened event carrying the popup's window ID.
5. Discover the buttons with GET /v2/tools?windowId={popupId}: cb_1 = "Yes, Proceed Anyway", cb_2 = "No, Cancel". Run cb_1 via POST /v2/tools with the popup's window ID; the save then commits.

Which items trip the rule is deterministic, not environmental luck: a site-configured DynaChange rule fires on every save of the Item window, and you can identify it — and usually fix the data instead — before writing any code. See Item Issues Detected — Root Cause and Data Fix. Use this interactive path for the cases you cannot data-fix; don't hard-code a fallback list of items.

Credit: Alex Westemeier.

Worked Example: w_message ("Save changes before closing?")

Every window can pop a w_message the same way: close it with an unsaved change pending. Built on the PurchaseOrder Notepad Writes recipe — same window, same cb_add popup — extended by one step. Verified end-to-end on 26.1.5930.1 and re-run in full on 26.1.5950.0 (September 2026):

1. Run steps 1–5 of Recipe: Add a Header Note: open PurchaseOrder (session with ResponseWindowHandlingEnabled: true), load a PO, add a header note through the w_notepad_response_lite popup (cb_add → fill topic/note → cb_select_all → cb_ok) — but stop before step 6's save. The note is staged in the window, not in the database yet.
2. Close the window instead of saving it: DELETE /v2/window?id={windowId}. Result: Status: 3 (Blocked) with a windowopened event.
3. GET /v2/window?id={popupId} → Definition.Name: "w_message", Definition.Title: "Epicor Prophet 21 - Startup", and Definition.Datawindows / Definition.TabPageList both empty.
4. GET /v2/tools?windowId={popupId} → button set: cb_1 (&Yes), cb_2 (&No), cb_3 (Cancel), plus the standard cb_print/cb_userinput/cb_copy chrome.
5. POST /v2/tools with ToolName: "cb_1" saves the note, then closes — a fresh window load shows it on file. ToolName: "cb_2" closes without saving — the fresh reload shows no such note.

Both of these responses nest the fields you want one level down, and neither key is named what you would guess. The GET /window payload is {"Definition": {…}, "Data": []} — Name, Title, Datawindows and TabPageList are all inside Definition, so a client reading top-level Title gets null and concludes the popup is anonymous. The GET /tools array identifies each button as ToolName, not Name — read Name and every button comes back null, which looks exactly like "this window exposes no usable tools" and is the likeliest way to re-derive the old, wrong conclusion below.

With ResponseWindowHandlingEnabled: false this sequence never reaches the w_message at all: step 1's cb_add fails first, with HTTP 400 naming the window it refused to open —

{"ErrorMessage": "Unexpected response window: Notepad Entry Window. Window class: w_notepad_response_lite"}

Under false, a response window that is not a plain message box is a hard error carrying its class name rather than a silent auto-answer — noisy, but far easier to diagnose than the message-box case. A w_message reached by some other route is auto-answered with its default, and the answer P21 gave itself is echoed in Messages as "<question text> [Response: Yes]" — observed on the Item window's GL-account sync prompt, fired by changing a location's product_group_id.

Credit: @yeshayak found that w_message is drivable and wrote this example; re-verified here on 26.1.5950.0, which is where the false-mode behaviour above and the two nesting traps were added.

Changing Tabs

Before changing fields on a different tab, select the tab first:

v2 Format (Recommended):

PUT /api/ui/interactive/v2/tab
{
    "WindowId": "w_sales_price_page",
    "PageName": "VALUES"
}

Note: In v2, use PageName directly. In v1, use PagePath: { PageName: "..." }.

v1 Format (Legacy):

PUT /api/ui/interactive/v1/tab
{
    "WindowId": "w_sales_price_page",
    "PagePath": {
        "PageName": "VALUES"
    }
}

Running Tools (Buttons)

Tools include all buttons and right-click (RMB) options available at any point in a session. They exist at three levels:

1. Window level — Ribbon buttons, window-level buttons
2. Datawindow level — Grid/form buttons, RMB options on a datawindow
3. Field level — Field-specific RMB options

Get Available Tools

Query tools at different levels by specifying optional parameters:

GET /api/ui/interactive/v2/tools?windowId=w_sales_price_page
GET /api/ui/interactive/v2/tools?windowId=w_sales_price_page&dwName=form
GET /api/ui/interactive/v2/tools?windowId=w_sales_price_page&dwName=form&fieldName=description&row=0

Run a Tool

POST /api/ui/interactive/v2/tools
{
    "WindowId": "w_sales_price_page",
    "ToolName": "cb_save",
    "ToolText": "Save"
}

The key must be ToolName. Posting the button under Name — the spelling most other P21 payloads use — is accepted and does nothing: P21 returns Status: 2 (Failure) with no message, so the tool never runs and a popup you were trying to dismiss stays open. Verified live on 26.1. GET /v2/tools returns the buttons under ToolName too; carry that key straight through to the POST rather than re-mapping it.

For datawindow or field-level tools, include the optional fields:

{
    "WindowId": "w_sales_price_page",
    "ToolName": "tool_name",
    "ToolText": "Tool Label",
    "DatawindowName": "form",
    "FieldName": "description",
    "Row": 0
}

Python and C# Examples

Basic Client Class

The minimum viable Interactive client: authenticate, resolve the UI server, open a session with the session parameters, read it back from GET /sessions, and always delete it. Complete program — it is also the quickest way to print your middleware build, since P21 exposes no version endpoint.

"""Open an Interactive session, print the middleware build, and clean it up."""
import re

import httpx

# ---- EDIT THESE -----------------------------------------------------------
BASE_URL = "https://play.p21server.com"   # your P21 server
USERNAME = "apiuser"
PASSWORD = "your-password"
VERIFY_SSL = False                        # True once you trust the cert chain
SESSION_TYPE = "Auto"                     # User | Auto | AutoInteractive
SESSION_TIMEOUT = 120                     # inactivity seconds before cleanup
CLIENT_APP = "PricePageSync"              # shows up in server-side logging
WORKSTATION_ID = "INTEGRATION-01"         # your identifier for this machine
# ---------------------------------------------------------------------------


def get_token(client: httpx.Client) -> str:
    """v2 token endpoint — credentials go in the body, never in headers."""
    r = client.post(
        f"{BASE_URL}/api/security/token/v2",
        json={"username": USERNAME, "password": PASSWORD},
        headers={"Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["AccessToken"]
    except (ValueError, KeyError):  # some middleware answers in XML
        match = re.search(r"<AccessToken>([^<]+)</AccessToken>", r.text)
        if not match:
            raise ValueError(f"No AccessToken in response: {r.text[:200]}") from None
        return match.group(1)


def get_ui_server(client: httpx.Client, token: str) -> str:
    """Transaction and Interactive calls go to the UI server, not BASE_URL."""
    r = client.get(
        f"{BASE_URL}/api/ui/router/v1/?urlType=external",  # trailing slash avoids a 307
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["Url"].rstrip("/")
    except (ValueError, KeyError):
        match = re.search(r"<Url>([^<]+)</Url>", r.text)
        if not match:
            raise ValueError(f"No Url in router response: {r.text[:200]}") from None
        return match.group(1).rstrip("/")


with httpx.Client(verify=VERIFY_SSL, timeout=120, follow_redirects=True) as client:
    token = get_token(client)
    ui_server = get_ui_server(client, token)
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",       # without this you get XML, not JSON
        "Content-Type": "application/json",
    }

    try:
        r = client.post(
            f"{ui_server}/api/ui/interactive/sessions",
            headers=headers,
            json={
                "SessionType": SESSION_TYPE,
                "SessionTimeout": SESSION_TIMEOUT,
                "ResponseWindowHandlingEnabled": False,
                "ClientPlatformApp": CLIENT_APP,
                "WorkstationID": WORKSTATION_ID,
            },
        )
        r.raise_for_status()
        session = r.json()

        # 25.2 returns SessionId; 2026.1 renamed it Id — read either.
        print("session:", session.get("Id") or session.get("SessionId"))

        # There is no version endpoint: the build rides the create response.
        for prop in session.get("Properties", []):
            build = (prop.get("Properties") or {}).get("fullversion")
            if build:
                print("middleware build:", build)

        # Read-back: list the sessions the server thinks are open.
        r = client.get(f"{ui_server}/api/ui/interactive/sessions", headers=headers)
        r.raise_for_status()
        print("open sessions:", r.text[:400])
    finally:
        # A session left behind 409s ("Session already exists") on the next
        # create — including the ghost left by a failed create. DELETE clears
        # it instantly; don't wait out SessionCleanupExpiration.
        client.delete(f"{ui_server}/api/ui/interactive/sessions", headers=headers)

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// ---- EDIT THESE -----------------------------------------------------------
const string BaseUrl = "https://play.p21server.com";   // your P21 server
const string Username = "apiuser";
const string Password = "your-password";
const string SessionType = "Auto";                     // User | Auto | AutoInteractive
const int SessionTimeout = 120;                        // inactivity seconds before cleanup
const string ClientApp = "PricePageSync";              // shows up in server-side logging
const string WorkstationId = "INTEGRATION-01";         // your identifier for this machine
// ---------------------------------------------------------------------------

var handler = new HttpClientHandler
{
    // Test tenants often present a self-signed cert. Delete this line in production.
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(2) };
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var token = await GetTokenAsync(client);
var uiServer = await GetUiServerAsync(client, token);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

try
{
    var createResponse = await client.PostAsync(
        $"{uiServer}/api/ui/interactive/sessions",
        Json(new
        {
            SessionType,
            SessionTimeout,
            ResponseWindowHandlingEnabled = false,
            ClientPlatformApp = ClientApp,
            WorkstationID = WorkstationId,
        }));
    createResponse.EnsureSuccessStatusCode();

    using (var session = JsonDocument.Parse(await createResponse.Content.ReadAsStringAsync()))
    {
        // 25.2 returns SessionId; 2026.1 renamed it Id — read either.
        var root = session.RootElement;
        Console.WriteLine($"session: {Field(root, "Id") ?? Field(root, "SessionId")}");

        // There is no version endpoint: the build rides the create response.
        if (root.TryGetProperty("Properties", out var properties))
            foreach (var property in properties.EnumerateArray())
                if (property.TryGetProperty("Properties", out var inner) &&
                    inner.TryGetProperty("fullversion", out var build))
                    Console.WriteLine($"middleware build: {build}");
    }

    // Read-back: list the sessions the server thinks are open.
    var listResponse = await client.GetAsync($"{uiServer}/api/ui/interactive/sessions");
    listResponse.EnsureSuccessStatusCode();
    var body = await listResponse.Content.ReadAsStringAsync();
    Console.WriteLine($"open sessions: {body[..Math.Min(400, body.Length)]}");
}
finally
{
    // A session left behind 409s ("Session already exists") on the next create —
    // including the ghost left by a failed create. DELETE clears it instantly;
    // don't wait out SessionCleanupExpiration.
    await client.DeleteAsync($"{uiServer}/api/ui/interactive/sessions");
}

// --- helpers ---------------------------------------------------------------

static StringContent Json(object body) =>
    new(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");

static string? Field(JsonElement element, string name) =>
    element.TryGetProperty(name, out var value) ? value.ToString() : null;

// v2 token endpoint — credentials go in the body, never in headers.
static async Task<string> GetTokenAsync(HttpClient client)
{
    var payload = JsonSerializer.Serialize(new { username = Username, password = Password });
    var response = await client.PostAsync(
        $"{BaseUrl}/api/security/token/v2",
        new StringContent(payload, Encoding.UTF8, "application/json"));
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "AccessToken");
}

// Transaction and Interactive calls go to the UI server, not BaseUrl.
static async Task<string> GetUiServerAsync(HttpClient client, string token)
{
    using var request = new HttpRequestMessage(
        HttpMethod.Get, $"{BaseUrl}/api/ui/router/v1/?urlType=external");
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var response = await client.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "Url").TrimEnd('/');
}

// Some middleware answers these two endpoints in XML even when asked for JSON.
static string ReadField(string payload, string field)
{
    try
    {
        var value = JsonDocument.Parse(payload).RootElement.GetProperty(field).GetString();
        if (!string.IsNullOrEmpty(value)) return value;
    }
    catch (Exception ex) when (ex is JsonException or KeyNotFoundException) { }

    var match = System.Text.RegularExpressions.Regex.Match(payload, $"<{field}>([^<]+)</{field}>");
    if (!match.Success)
        throw new InvalidOperationException(
            $"No {field} in response: {payload[..Math.Min(200, payload.Length)]}");
    return match.Groups[1].Value;
}

Context Manager / Disposable Usage (Sync)

Structural sketch, not a runnable program — it shows only the lifecycle hooks wrapped around the methods above, and open_window / change_data / save are your own thin wrappers over the REST calls.

Full runnable version: Basic Client Class

class InteractiveClient:
    # ... methods above ...

    def __enter__(self):
        self.authenticate()
        self.get_ui_server()
        self.start_session()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        try:
            self.end_session()
        except Exception:
            pass
        return False

# Usage
with InteractiveClient(base_url, username, password) as client:
    window = client.open_window("SalesPricePage")
    window.change_data("description", "New Value")
    window.save()
    window.close()

public class InteractiveClient : IDisposable
{
    // ... fields and methods above ...

    public InteractiveClient Connect()
    {
        AuthenticateAsync().GetAwaiter().GetResult();
        GetUiServerAsync().GetAwaiter().GetResult();
        StartSessionAsync().GetAwaiter().GetResult();
        return this;
    }

    public void Dispose()
    {
        try { EndSessionAsync().GetAwaiter().GetResult(); }
        catch (Exception) { /* ignored */ }
        _http.Dispose();
    }
}

// Usage
using var client = new InteractiveClient(baseUrl, username, password).Connect();
var window = client.OpenWindow("SalesPricePage");
window.ChangeData("description", "New Value");
window.Save();
window.Close();

Async Context Manager / IAsyncDisposable (Recommended)

For production code, use async patterns with proper cleanup. Structural sketch — the elided bodies (# ... get ui_server_url and start session ...) are the calls shown in full below.

Full runnable version: Basic Client Class

import httpx
import logging

logger = logging.getLogger(__name__)

class P21Client:
    def __init__(
        self, base_url: str, username: str,
        password: str, verify_ssl: bool = True,
    ):
        self.base_url = base_url.rstrip('/')
        self.username = username
        self.password = password
        self.verify_ssl = verify_ssl
        self.token: dict | None = None
        self.ui_server_url: str | None = None
        self._client: httpx.AsyncClient | None = None

    def _get_client(self) -> httpx.AsyncClient:
        if self._client is None or self._client.is_closed:
            self._client = httpx.AsyncClient(
                verify=self.verify_ssl,
                timeout=60.0,
                follow_redirects=True
            )
        return self._client

    async def authenticate(self) -> dict:
        url = f"{self.base_url}/api/security/token/v2"
        client = self._get_client()
        response = await client.post(
            url, json={"username": self.username, "password": self.password}
        )
        response.raise_for_status()
        self.token = response.json()
        return self.token

    async def start_session(self) -> None:
        if not self.token:
            await self.authenticate()
        # ... get ui_server_url and start session ...

    async def end_session(self) -> None:
        # ... end session ...
        pass

    async def close(self) -> None:
        if self._client and not self._client.is_closed:
            await self._client.aclose()
            self._client = None

    async def __aenter__(self):
        """Async context manager entry - authenticate and start session."""
        await self.authenticate()
        await self.start_session()
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Async context manager exit - end session and close client."""
        try:
            await self.end_session()
        except Exception as e:
            logger.debug(f"Session cleanup error (ignored): {e}")
        await self.close()
        return False

# Usage
async with P21Client(base_url, username, password) as client:
    window = await client.open_window(service_name="SalesPricePage")
    await window.change_data("FORM", "description", "New Value", datawindow_name="form")
    await window.save_data()
    await window.close()

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

public class P21Client : IAsyncDisposable
{
    private readonly string _baseUrl;
    private readonly string _username;
    private readonly string _password;
    private HttpClient? _http;
    private string? _token;
    private string? _uiServerUrl;

    public P21Client(string baseUrl, string username, string password,
                     bool verifySsl = true)
    {
        _baseUrl = baseUrl.TrimEnd('/');
        _username = username;
        _password = password;
        var handler = new HttpClientHandler();
        if (!verifySsl)
            handler.ServerCertificateCustomValidationCallback = (_, _, _, _) => true;

        _http = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(60) };
    }

    public async Task<JsonElement> AuthenticateAsync()
    {
        var body = JsonSerializer.Serialize(new { username = _username, password = _password });
        var content = new StringContent(body.ToString(), System.Text.Encoding.UTF8, "application/json");
        var response = await _http!.PostAsync($"{_baseUrl}/api/security/token/v2", content);
        response.EnsureSuccessStatusCode();

        using var parsed = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
        _token = parsed["AccessToken"]!.ToString();
        _http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _token);
        return parsed;
    }

    public async Task StartSessionAsync()
    {
        if (_token == null)
            await AuthenticateAsync();
        // ... get uiServerUrl and start session ...
    }

    public async Task EndSessionAsync()
    {
        // ... end session ...
    }

    public async ValueTask DisposeAsync()
    {
        try
        {
            await EndSessionAsync();
        }
        catch (Exception ex)
        {
            Console.Error.WriteLine($"Session cleanup error (ignored): {ex.Message}");
        }

        _http?.Dispose();
        _http = null;
    }
}

// Usage
await using var client = new P21Client(baseUrl, username, password);
await client.AuthenticateAsync();
await client.StartSessionAsync();
var window = await client.OpenWindowAsync(serviceName: "SalesPricePage");
await window.ChangeDataAsync("FORM", "description", "New Value", datawindowName: "form");
await window.SaveDataAsync();
await window.CloseAsync();

Key points for async usage:

1. Use httpx.AsyncClient (Python) or HttpClient with async/await (C#)
2. Implement __aenter__/__aexit__ (Python) or IAsyncDisposable (C#)
3. Always close the HTTP client on disposal
4. Ignore cleanup errors - session may have timed out
5. Use async with (Python) or await using (C#) for guaranteed cleanup

Working Example Scripts

See the examples/python/interactive/ directory:

Common Windows

Production & Labor Windows

Pick confirmation MUST be windowed. A Transaction-API-only confirm produces a shell — the status flips and qty_confirmed is set, but qty_applied stays 0 and no stock moves. See Confirming the Pick.

See Production & Labor API for detailed field definitions.

Example: Linking Price Page to Price Book

This example shows how to use the SalesPriceBook window to link a price page to a price book. This is a common operation after creating a new price page.

Complete program — session, window, retrieve, tab switch, add row, change, save, read-back, cleanup. It is the reference for every "change a field / add a grid row / save" sequence in this guide.

"""Link a price page to a price book through the SalesPriceBook window."""
import re

import httpx

# ---- EDIT THESE -----------------------------------------------------------
BASE_URL = "https://play.p21server.com"   # your P21 server
USERNAME = "apiuser"
PASSWORD = "your-password"
VERIFY_SSL = False                        # True once you trust the cert chain
PRICE_BOOK_ID = "ACME_BOOK_A"             # the book to load on the FORM tab
PRICE_PAGE_UID = "100198"                 # the page to link — sent as a string
# ---------------------------------------------------------------------------


def get_token(client: httpx.Client) -> str:
    """v2 token endpoint — credentials go in the body, never in headers."""
    r = client.post(
        f"{BASE_URL}/api/security/token/v2",
        json={"username": USERNAME, "password": PASSWORD},
        headers={"Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["AccessToken"]
    except (ValueError, KeyError):  # some middleware answers in XML
        match = re.search(r"<AccessToken>([^<]+)</AccessToken>", r.text)
        if not match:
            raise ValueError(f"No AccessToken in response: {r.text[:200]}") from None
        return match.group(1)


def get_ui_server(client: httpx.Client, token: str) -> str:
    """Transaction and Interactive calls go to the UI server, not BASE_URL."""
    r = client.get(
        f"{BASE_URL}/api/ui/router/v1/?urlType=external",  # trailing slash avoids a 307
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["Url"].rstrip("/")
    except (ValueError, KeyError):
        match = re.search(r"<Url>([^<]+)</Url>", r.text)
        if not match:
            raise ValueError(f"No Url in router response: {r.text[:200]}") from None
        return match.group(1).rstrip("/")


with httpx.Client(verify=VERIFY_SSL, timeout=120, follow_redirects=True) as client:
    token = get_token(client)
    ui_server = get_ui_server(client, token)
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",       # without this you get XML, not JSON
        "Content-Type": "application/json",
    }

    def check(response: httpx.Response, step: str) -> dict:
        """Raise unless the call returned Status 1 (Success)."""
        response.raise_for_status()
        result = response.json()
        status = result.get("Status")
        messages = [m.get("Text") for m in result.get("Messages", [])]
        if status not in (1, "Success"):
            raise RuntimeError(f"{step}: Status={status} {messages}")
        if messages:
            print(f"{step}: {messages}")
        return result

    r = client.post(
        f"{ui_server}/api/ui/interactive/sessions",
        headers=headers,
        json={"ResponseWindowHandlingEnabled": False},
    )
    r.raise_for_status()
    session = r.json()
    print("session:", session.get("Id") or session.get("SessionId"))

    window_id = None
    try:
        # Open by ServiceName — the by-Name and by-Title paths are unreliable.
        r = client.post(
            f"{ui_server}/api/ui/interactive/v2/window",
            headers=headers,
            json={"ServiceName": "SalesPriceBook"},
        )
        r.raise_for_status()
        opened = r.json()
        window_id = opened.get("WindowId") or opened.get("Id")

        # Step 1: retrieve the book by ID on the FORM tab. DatawindowName is
        # required from 25.2 on — the 3-parameter form stopped working.
        check(
            client.put(
                f"{ui_server}/api/ui/interactive/v2/change",
                headers=headers,
                json={
                    "WindowId": window_id,
                    "List": [
                        {
                            "TabName": "FORM",
                            "DatawindowName": "form",
                            "FieldName": "price_book_id",
                            "Value": PRICE_BOOK_ID,
                        }
                    ],
                },
            ),
            "retrieve book",
        )

        # Step 2: switch to the LIST tab (v2 binds PageName, not TabName)
        check(
            client.put(
                f"{ui_server}/api/ui/interactive/v2/tab",
                headers=headers,
                json={"WindowId": window_id, "PageName": "LIST"},
            ),
            "select LIST tab",
        )

        # Step 3: add a new row to the list_detail datawindow
        check(
            client.post(
                f"{ui_server}/api/ui/interactive/v2/row",
                headers=headers,
                json={"WindowId": window_id, "DatawindowName": "list_detail"},
            ),
            "add row",
        )

        # Step 4: set price_page_uid on the new row
        check(
            client.put(
                f"{ui_server}/api/ui/interactive/v2/change",
                headers=headers,
                json={
                    "WindowId": window_id,
                    "List": [
                        {
                            "TabName": "LIST",
                            "DatawindowName": "list_detail",
                            "FieldName": "price_page_uid",
                            "Value": PRICE_PAGE_UID,
                        }
                    ],
                },
            ),
            "set price_page_uid",
        )

        # Step 5: save — the v2 body is the bare window-id GUID as a JSON
        # string, NOT wrapped in an object (a wrapped body 422s).
        check(
            client.put(
                f"{ui_server}/api/ui/interactive/v2/data",
                headers=headers,
                json=window_id,
            ),
            "save",
        )

        # Step 6: read back. /v2/data returns only a varying subset of the
        # window's datawindows, so the LIST tab must be active — and absence
        # still proves nothing. For records that matter, verify out of band
        # too (see "Verifying Writes").
        r = client.get(
            f"{ui_server}/api/ui/interactive/v2/data",
            headers=headers,
            params={"id": window_id},
        )
        r.raise_for_status()
        for dw in r.json():
            if dw.get("Name") == "list_detail":
                print("columns:", dw.get("Columns"))
                for row in dw.get("Data", []):
                    print("row:", row)
    finally:
        if window_id:
            client.delete(
                f"{ui_server}/api/ui/interactive/v2/window",
                headers=headers,
                params={"id": window_id},
            )
        client.delete(f"{ui_server}/api/ui/interactive/sessions", headers=headers)

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// ---- EDIT THESE -----------------------------------------------------------
const string BaseUrl = "https://play.p21server.com";   // your P21 server
const string Username = "apiuser";
const string Password = "your-password";
const string PriceBookId = "ACME_BOOK_A";              // the book to load on the FORM tab
const string PricePageUid = "100198";                  // the page to link — sent as a string
// ---------------------------------------------------------------------------

var handler = new HttpClientHandler
{
    // Test tenants often present a self-signed cert. Delete this line in production.
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(2) };
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var token = await GetTokenAsync(client);
var uiServer = await GetUiServerAsync(client, token);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var sessionResponse = await client.PostAsync(
    $"{uiServer}/api/ui/interactive/sessions",
    Json(new { ResponseWindowHandlingEnabled = false }));
sessionResponse.EnsureSuccessStatusCode();
using (var session = JsonDocument.Parse(await sessionResponse.Content.ReadAsStringAsync()))
    Console.WriteLine($"session: {Field(session.RootElement, "Id") ?? Field(session.RootElement, "SessionId")}");

string? windowId = null;
try
{
    // Open by ServiceName — the by-Name and by-Title paths are unreliable.
    var openResponse = await client.PostAsync(
        $"{uiServer}/api/ui/interactive/v2/window",
        Json(new { ServiceName = "SalesPriceBook" }));
    openResponse.EnsureSuccessStatusCode();
    using (var opened = JsonDocument.Parse(await openResponse.Content.ReadAsStringAsync()))
        windowId = Field(opened.RootElement, "WindowId") ?? Field(opened.RootElement, "Id");

    // Step 1: retrieve the book by ID on the FORM tab. DatawindowName is
    // required from 25.2 on — the 3-parameter form stopped working.
    await Check(await client.PutAsync(
        $"{uiServer}/api/ui/interactive/v2/change",
        Json(new
        {
            WindowId = windowId,
            List = new[]
            {
                new
                {
                    TabName = "FORM",
                    DatawindowName = "form",
                    FieldName = "price_book_id",
                    Value = PriceBookId,
                },
            },
        })), "retrieve book");

    // Step 2: switch to the LIST tab (v2 binds PageName, not TabName)
    await Check(await client.PutAsync(
        $"{uiServer}/api/ui/interactive/v2/tab",
        Json(new { WindowId = windowId, PageName = "LIST" })), "select LIST tab");

    // Step 3: add a new row to the list_detail datawindow
    await Check(await client.PostAsync(
        $"{uiServer}/api/ui/interactive/v2/row",
        Json(new { WindowId = windowId, DatawindowName = "list_detail" })), "add row");

    // Step 4: set price_page_uid on the new row
    await Check(await client.PutAsync(
        $"{uiServer}/api/ui/interactive/v2/change",
        Json(new
        {
            WindowId = windowId,
            List = new[]
            {
                new
                {
                    TabName = "LIST",
                    DatawindowName = "list_detail",
                    FieldName = "price_page_uid",
                    Value = PricePageUid,
                },
            },
        })), "set price_page_uid");

    // Step 5: save — the v2 body is the bare window-id GUID as a JSON string,
    // NOT wrapped in an object (a wrapped body 422s).
    await Check(await client.PutAsync(
        $"{uiServer}/api/ui/interactive/v2/data",
        new StringContent(JsonSerializer.Serialize(windowId), Encoding.UTF8, "application/json")),
        "save");

    // Step 6: read back. /v2/data returns only a varying subset of the window's
    // datawindows, so the LIST tab must be active — and absence still proves
    // nothing. For records that matter, verify out of band too.
    var dataResponse = await client.GetAsync(
        $"{uiServer}/api/ui/interactive/v2/data?id={windowId}");
    dataResponse.EnsureSuccessStatusCode();

    using var data = JsonDocument.Parse(await dataResponse.Content.ReadAsStringAsync());
    foreach (var dw in data.RootElement.EnumerateArray())
    {
        if (Field(dw, "Name") != "list_detail") continue;
        Console.WriteLine($"columns: {Field(dw, "Columns")}");
        if (dw.TryGetProperty("Data", out var rows))
            foreach (var row in rows.EnumerateArray())
                Console.WriteLine($"row: {row}");
    }
}
finally
{
    if (windowId is not null)
        await client.DeleteAsync($"{uiServer}/api/ui/interactive/v2/window?id={windowId}");

    await client.DeleteAsync($"{uiServer}/api/ui/interactive/sessions");
}

// --- helpers ---------------------------------------------------------------

// Raise unless the call returned Status 1 (Success).
static async Task<JsonDocument> Check(HttpResponseMessage response, string step)
{
    response.EnsureSuccessStatusCode();
    var result = JsonDocument.Parse(await response.Content.ReadAsStringAsync());

    var status = Field(result.RootElement, "Status");
    var messages = new List<string>();
    if (result.RootElement.TryGetProperty("Messages", out var items))
        messages = items.EnumerateArray().Select(m => Field(m, "Text") ?? "").ToList();

    if (status != "1" && status != "Success")
        throw new InvalidOperationException(
            $"{step}: Status={status} {string.Join("; ", messages)}");
    if (messages.Count > 0)
        Console.WriteLine($"{step}: {string.Join("; ", messages)}");

    return result;
}

static StringContent Json(object body) =>
    new(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");

static string? Field(JsonElement element, string name) =>
    element.TryGetProperty(name, out var value) ? value.ToString() : null;

// v2 token endpoint — credentials go in the body, never in headers.
static async Task<string> GetTokenAsync(HttpClient client)
{
    var payload = JsonSerializer.Serialize(new { username = Username, password = Password });
    var response = await client.PostAsync(
        $"{BaseUrl}/api/security/token/v2",
        new StringContent(payload, Encoding.UTF8, "application/json"));
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "AccessToken");
}

// Transaction and Interactive calls go to the UI server, not BaseUrl.
static async Task<string> GetUiServerAsync(HttpClient client, string token)
{
    using var request = new HttpRequestMessage(
        HttpMethod.Get, $"{BaseUrl}/api/ui/router/v1/?urlType=external");
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var response = await client.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "Url").TrimEnd('/');
}

// Some middleware answers these two endpoints in XML even when asked for JSON.
static string ReadField(string payload, string field)
{
    try
    {
        var value = JsonDocument.Parse(payload).RootElement.GetProperty(field).GetString();
        if (!string.IsNullOrEmpty(value)) return value;
    }
    catch (Exception ex) when (ex is JsonException or KeyNotFoundException) { }

    var match = System.Text.RegularExpressions.Regex.Match(payload, $"<{field}>([^<]+)</{field}>");
    if (!match.Success)
        throw new InvalidOperationException(
            $"No {field} in response: {payload[..Math.Min(200, payload.Length)]}");
    return match.Groups[1].Value;
}