P21 API Overview¶

Epicor Prophet 21 exposes five distinct API families through its application server. Each family operates at a different abstraction level and is optimized for different use cases. This page provides a consolidated reference for all API base URLs, authentication requirements, supported formats, and common HTTP conventions.

API Summary¶

API	Base Path	Auth Method	Supported Formats
Common Services	`/uiserver0/ui/common/v1/`	Session (Basic → Session Token)	XML, JSON
Interactive API	`/uiserver0/ui/interactive/v1/`	Session Token	XML, JSON
Transaction API	`/uiserver0/ui/interactive/transaction/`	Session Token	XML, JSON
Entity API	`/api/entity/`	Bearer Token	XML
Data Services	`/api/dataservices/`	Bearer Token	JSON (OData v4)

Full Base URLs¶

# UI-based APIs
https://{your-server}/uiserver0/ui/common/v1/
https://{your-server}/uiserver0/ui/interactive/v1/
https://{your-server}/uiserver0/ui/interactive/transaction/

# REST APIs
https://{your-server}/api/entity/
https://{your-server}/api/dataservices/

URL Root Distinction

The /uiserver0/ root hosts the session-based UI service APIs. The /api/ root hosts the stateless REST and OData APIs. These are different services on the P21 application server and use different authentication mechanisms.

URL Patterns¶

UI-Based APIs (`/uiserver0/`)¶

The UI-based APIs follow a consistent URL pattern:

https://{server}/uiserver0/ui/{api-name}/{version}/{resource}/

For example:

https://{server}/uiserver0/ui/common/v1/sessions/
https://{server}/uiserver0/ui/common/v1/sessions/state
https://{server}/uiserver0/ui/interactive/v1/windows/

All endpoints under /uiserver0/ require an active session. The session token must be present on every request after the initial POST /sessions/ call.

REST APIs (`/api/`)¶

The REST APIs follow standard resource-based URL patterns:

https://{server}/api/entity/{EntityName}
https://{server}/api/dataservices/{ViewName}

For example:

https://{server}/api/entity/Customer
https://{server}/api/entity/SalesOrder?order_no=100001
https://{server}/api/dataservices/p21_view_customer?$filter=company_id eq '01'

Common HTTP Conventions¶

All P21 APIs follow standard HTTP conventions with a few P21-specific behaviors to be aware of.

HTTP Methods¶

Method	Typical Use
`GET`	Retrieve a resource or collection
`POST`	Create a new resource; also used for some operations (session create, ping)
`PUT`	Replace a resource entirely
`PATCH`	Partial update of a resource
`DELETE`	Remove a resource
`OPTIONS`	Preflight check for CORS (browser clients)

Content Negotiation¶

The UI-based APIs (Common Services, Interactive, Transaction) support both XML and JSON. Set the appropriate headers:

Content-Type: application/json
Accept: application/json

or

Content-Type: application/xml
Accept: application/xml

The default format varies by endpoint — specify Accept explicitly to ensure you receive the format you expect.

JSON Is Easier to Work With

For new integrations targeting the UI-based APIs, use JSON. It is easier to parse and debug than XML, and the P21 APIs support it fully.

The Entity API returns XML only. The Data Services API returns JSON (OData format) by default.

CORS and Preflight¶

If you are calling P21 APIs from a browser (JavaScript/TypeScript frontend), the browser will issue an OPTIONS preflight request before the actual API call. P21 handles this automatically for configured origins.

For server-to-server integrations (the most common pattern), CORS is not relevant — only browsers enforce it.

OPTIONS — Service Discovery¶

You can send an OPTIONS request to any endpoint to retrieve the WADL (Web Application Description Language) metadata for that endpoint, including supported methods and parameters:

OPTIONS https://{server}/uiserver0/ui/common/v1/sessions/

Authentication Quick Reference¶

Session-Based Auth (UI APIs)¶

POST /common/v1/sessions/ with Authorization: Basic {base64(user:pass)}
Extract session token from response
Include X-SessionToken: {token} on all subsequent calls
DELETE /common/v1/sessions/ when done

Bearer Token Auth (REST APIs)¶

Include on every request:

Authorization: Bearer {your-token}

Full authentication details are in the Authentication guide.

Standard Response Formats¶

Success — JSON (UI-Based APIs)¶

{
  "SessionID": "abc123",
  "UserID": "jsmith",
  "CompanyID": "01"
}

Success — OData JSON (Data Services)¶

{
  "@odata.context": "https://{server}/api/dataservices/$metadata#p21_view_customer",
  "@odata.count": 1250,
  "value": [
    {
      "customer_id": "C0001",
      "customer_name": "Acme Corp",
      "phone": "555-0100"
    }
  ]
}

Success — XML (Entity API)¶

<Customer xmlns="...">
  <customer_id>C0001</customer_id>
  <customer_name>Acme Corp</customer_name>
  <phone>555-0100</phone>
</Customer>

Error Handling¶

P21 APIs return standard HTTP status codes. Always check the status code before attempting to parse the response body.

Common HTTP Status Codes¶

Status Code	Meaning	Common Cause
`200 OK`	Success	Request completed normally
`201 Created`	Resource created	Successful POST that created a record
`400 Bad Request`	Invalid input	Malformed request body, missing required fields
`401 Unauthorized`	Auth failure	Missing or invalid credentials / expired session
`403 Forbidden`	Access denied	Valid session but insufficient P21 security role
`404 Not Found`	Resource not found	Record does not exist; invalid endpoint URL
`409 Conflict`	Conflict	Duplicate record; constraint violation
`500 Internal Server Error`	Server error	P21 application error; check server logs
`503 Service Unavailable`	Service down	P21 application server is not running or overloaded

Error Response Body¶

P21 errors typically include a message in the response body. For JSON:

{
  "Message": "Session token is invalid or has expired.",
  "ErrorCode": "SESSION_INVALID"
}

For XML:

<Error>
  <Message>Record not found: customer_id = XXXXX</Message>
  <ErrorCode>RECORD_NOT_FOUND</ErrorCode>
</Error>

Log the Full Response on Errors

Always log the full response body when handling non-2xx responses. P21 error messages are usually descriptive and will tell you exactly what went wrong.

Recommended Error Handling Pattern (C#)¶

var response = await client.GetAsync(url);

if (!response.IsSuccessStatusCode)
{
    var errorBody = await response.Content.ReadAsStringAsync();
    throw new P21ApiException(
        $"P21 API error {(int)response.StatusCode}: {errorBody}",
        response.StatusCode);
}

var result = await response.Content.ReadAsStringAsync();

Service Availability¶

Checking If a Service Is Running¶

Use the Common Services info endpoint to verify the P21 API server is reachable and enumerate available services:

GET https://{server}/uiserver0/ui/common/v1/info/

This does not require a session and returns a list of all registered service endpoints.

Server Information¶

GET https://{server}/uiserver0/ui/common/v1/serverinfo/

Returns P21 version, build number, and server configuration details. Useful for confirming the target environment in multi-environment setups.

Entity API Health¶

The Entity API does not have a dedicated health endpoint. A lightweight check is to request a known small entity:

GET https://{server}/api/entity/
Authorization: Bearer {token}

A 200 response confirms the service is up and the token is valid.