Entity 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.

Status Update (February 2026): The Entity API is functional. Previous reports of it being non-functional were due to incorrect endpoint URLs. The customer/vendor/contact/address entities live under /api/entity/.

Terminology — Epicor's Naming (July 2026)

Epicor's own use of "Entity API" is broader than this document. In Epicor's naming (per the SOA middleware admin site):

• "Entity API" is an umbrella term covering two APIs:
• the REST API — which includes the /api/entity/, /api/inventory/, and /api/sales/ endpoint families, and
• the eCommerce API (also called the Entity SOAP API).
• URL segments are arbitrary — the word "entity" in a URL has no relationship to the "Entity API" term. Don't infer API boundaries from URL paths.
• This document covers the /api/entity/ endpoint family of the REST API. The Inventory REST API (/api/inventory/parts) is part of the same REST API, not a separate API — the two docs are split for readability only.
• Epicor briefly subdivided the REST API into "V1 API" / "V2 API" — short-lived naming you may still hear; it has no relation to /v2/ segments in eCommerce SOAP URLs.

Corroborated by the in-middleware SDK reference (/docs/p21sdk on a 2026.1 tenant), which is Epicor's own first-party catalog and lists exactly four APIs — no more:

Two things worth noting: Epicor confirms in its own words that the Transaction API is the artist formerly known as the "v2 API", and the SDK's four-way split is by capability, not by URL prefix — reinforcing that URL segments don't define API boundaries. The UDT Service and its 2026.1 Bulk Data API appear in none of the four, despite being documented, supported endpoints — so the SDK catalog is not exhaustive either.

Credit: Felipe Maurer (P21WWUG profile) — taxonomy correction and 25.1 middleware evidence in this forum topic; endpoint behavior re-verified live July 2026, SDK catalog cross-checked on 2026.1.

Overview

This document covers the stateless REST endpoints at /api/entity/ for CRUD (Create, Read, Update, Delete) operations on P21 business objects. They use domain object models and support four entities: Customer, Vendor, Contact, and Address.

The same REST API also provides /api/inventory/parts — see Inventory REST API — and an /api/sales/orders endpoint family (see Other REST Endpoint Families below).

Key Characteristics

• Stateless - No session management required
• Entity-based - Works with domain objects (not raw table rows)
• CRUD operations - Get, Create, Update via REST
• Query support - Filter with $query parameter
• Extended properties - Include related/nested data in responses
• User Defined Fields - UDF support when enabled in admin
• Dual format - Supports both JSON and XML (Accept header)

When to Use

• Customer, vendor, contact, or address lookups
• Basic CRUD on the 4 supported entities
• B2B integrations needing domain object models
• When you want cleaner data shapes than raw OData table rows

Limitations

• Only 4 entities at /api/entity/ - Orders live at /api/sales/orders (see Other REST Endpoint Families); no invoices, POs, or other business objects found
• Inventory documented separately - Lives at /api/inventory/parts, part of the same REST API (see Inventory REST API)
• Limited coverage - For broad data access, use OData (read) or Transaction API (write)

Base URL

https://{hostname}/api/entity/{resource}

Examples: - https://play.p21server.com/api/entity/customers - https://play.p21server.com/api/entity/vendors - https://play.p21server.com/api/entity/contacts - https://play.p21server.com/api/entity/addresses

Warning: Customer/vendor/contact/address records are served only from /api/entity/ — category-style URLs for those records (e.g., /api/sales/customers) return 404. But do not generalize that to "category URLs don't work": /api/sales/orders exists and responds (verified July 2026 — see Other REST Endpoint Families), and /api/inventory/parts is fully functional (Inventory REST API). All of these are endpoint families of the same REST API.

Available Entities

Only four entities are available via the Entity API:

Additionally, the same REST API provides inventory items at /api/inventory/parts (Inventory REST API) and sales orders at /api/sales/orders (below).

Composite Keys

Customers and Vendors require a composite key combining CompanyId and the entity ID, separated by an underscore:

/api/entity/customers/ACME_10          # CompanyId=ACME, CustomerId=10
/api/entity/vendors/ACME_28485        # CompanyId=ACME, VendorId=28485

• CompanyId is a string (e.g., "ACME"), not numeric
• Using just the numeric ID (e.g., /customers/10) returns 404
• The underscore can be URL-encoded (%5F) if needed

Contacts and Addresses use simple numeric IDs:

/api/entity/contacts/1
/api/entity/addresses/10

Vendor ID vs Supplier ID

The Entity API VendorId is not the same as the OData supplier_id. These come from different database tables. To find the correct VendorId, query vendors through the Entity API or check the vendor table via OData.

Endpoints Per Entity

Customers, Vendors, Contacts

Addresses (Limited)

Addresses have a reduced set of operations — no /new template and no update:

No /new or PUT: The address resource does not define a template endpoint or an update method in the SDK interface. The /new endpoint returns 500 because it doesn't exist (not a bug). To update an address, use the Interactive API or direct SQL.

Trailing Slash on List Endpoints

List endpoints (GET /api/entity/customers) return a 307 redirect to the same URL with a trailing slash (/api/entity/customers/). Configure your HTTP client to follow redirects:

client = httpx.Client(follow_redirects=True, ...)

var handler = new HttpClientHandler { AllowAutoRedirect = true };
var client = new HttpClient(handler);

Note: Be cautious with unfiltered list queries. The customers endpoint returned 19,896 records, contacts returned 58,639. Always use $query to filter when possible.

Authentication

Include the Bearer token in the Authorization header:

GET /api/entity/customers/ACME_10 HTTP/1.1
Host: play.p21server.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

See Authentication for token generation. Per the SDK, user-credential tokens expire after 24 hours; consumer-key tokens last far longer (years).

Consumer Key Behavior

When using Consumer Key authentication with the Entity API:

CRUD Operations

Key Rule: Presence = Update, Absence = Insert

The Entity API determines whether to insert or update based on whether key fields are present:

• Key absent (e.g., CustomerId is null or omitted) → Insert (create new record, system generates ID)
• Key present (e.g., CustomerId: 10) → Update (modify existing record)

This applies to all entities. When creating, omit or null-out the ID field. When updating, include the key both in the URL and body.

Read (GET)

Single record by key:

GET /api/entity/customers/ACME_10
Accept: application/json

Response:

{
    "CompanyId": "ACME",
    "CustomerId": 10,
    "CustomerName": "ABC Supply Company",
    "SalesrepId": "1100",
    "TermsId": "1",
    "CreditStatus": "GOOD",
    "CreditLimit": 1.0,
    "Taxable": "Y",
    "CurrencyId": 1,
    "CustomerType": "COM",
    "CustomerAddress": null,
    "CustomerContacts": null,
    "CustomerShipTos": null,
    "UserDefinedFields": {},
    "ObjectName": "customer"
}

Note: Nested objects (CustomerAddress, CustomerContacts, etc.) are null by default. Use extendedproperties to populate them.

Create (POST)

1. Get a template: GET /api/entity/customers/new
2. Fill in required fields
3. POST without key fields (absence of key = insert)

POST /api/entity/customers
Content-Type: application/json

{
    "CompanyId": "ACME",
    "CustomerName": "New Customer Inc.",
    "SalesrepId": "1100",
    "TermsId": "1",
    "CodRequiredFlag": "N",
    "Taxable": "Y"
}

Update (PUT)

Include the composite key in the URL:

PUT /api/entity/customers/ACME_10
Content-Type: application/json

{
    "CompanyId": "ACME",
    "CustomerId": 10,
    "CustomerName": "Updated Name"
}

Delete

Per the SDK, set the Delete field to true on an update:

PUT /api/entity/customers/ACME_10
Content-Type: application/json

{
    "CompanyId": "ACME",
    "CustomerId": 10,
    "Delete": true
}

Note: Dedicated DELETE HTTP method is not documented in the SDK for any entity.

Address Limitations

The Address entity has a reduced API surface compared to other entities:

• No /new template — GET /api/entity/addresses/new returns 500 (endpoint not implemented)
• No PUT (update) — The SDK interface only defines CreateAddress, not UpdateAddress
• Create only — You can create and read addresses, but not update them via this API

To update an existing address, use the Interactive API (Address Maintenance window) or direct SQL. See Error Handling - Entity API for the specific error codes these limitations produce.

Health Check (Ping)

Each entity has a /ping endpoint for verifying the service is running:

GET /api/entity/customers/ping

Response:

{
    "ResponseMessage": "success"
}

Query Syntax

Filter results using the $query parameter on list endpoints:

GET /api/entity/customers/?$query=startswith(CustomerName, 'ABC')

Remember: List endpoints redirect (307), so use a trailing slash or enable redirect following.

Comparison Operators

Logical Operators

String Functions

Verified Query Examples

# Find customers by name prefix (returned 7 results)
GET /api/entity/customers/?$query=startswith(CustomerName, 'ABC')

# Find vendors by name prefix (returned 6 results)
GET /api/entity/vendors/?$query=startswith(VendorName, 'ABC')

# Filter by company
GET /api/entity/customers/?$query=CompanyId eq 'ACME'

Extended Properties

Include related/nested data using the extendedproperties parameter:

All nested objects:

GET /api/entity/customers/ACME_10?extendedproperties=*

Specific nested object:

GET /api/entity/customers/ACME_10?extendedproperties=CustomerAddress

Available Extended Properties by Entity

Customer: - CustomerAddress - Mailing and physical address - CustomerEDITransactions - EDI configuration - CustomerSalesreps - Assigned sales reps - CustomerTerms - Payment terms - CustomerDealerTypes - Dealer type assignments - CustomerRestrictedClasses - Restricted product classes - CustomerContacts - Associated contacts - CustomerShipTos - Ship-to addresses - CustomerPriceLibraries - Price library assignments

Vendor: - VendorSuppliers - Associated supplier records - VendorAddress - Mailing and physical address - VendorPurchaseAccounts - Purchase account configuration - VendorContract - Contract information

Inventory: see the Inventory REST API extended properties reference for the full list for /api/inventory/parts.

Contact: - ContactDocuments - Associated documents - ContactLeadSources - Lead source tracking - ContactLinks - Related entity links - ContactLists - Mailing list membership - ContactSalesreps - Assigned sales reps

Example: Customer with Address

GET /api/entity/customers/ACME_10?extendedproperties=CustomerAddress

{
    "CompanyId": "ACME",
    "CustomerId": 10,
    "CustomerName": "ABC Supply Company",
    "CustomerAddress": {
        "CorpAddressId": 10,
        "MailAddress1": "123 Industrial Parkway",
        "MailCity": "Springfield",
        "MailState": "IL",
        "MailPostalCode": "62701",
        "MailCountry": "USA",
        "CentralPhoneNumber": "555-555-1234",
        "PhysAddress1": "123 Industrial Parkway",
        "PhysCity": "Springfield",
        "PhysState": "IL"
    }
}

User Defined Fields

Entity API supports User Defined Fields (UDFs) when enabled in the P21 middleware.

Enabling UDFs

1. Go to the Administration page: https://{hostname}/docs/admin.aspx
2. Toggle "User Defined Field Enabled Setting" to Enabled
3. Click "Regenerate User Defined Fields" if fields are not appearing

UDF Behavior

• UDFs appear in the response under the UserDefinedFields property
• UDFs are subordinate to the parent entity (cannot be modified independently)
• When creating/updating, include UDF values in the UserDefinedFields object

Response Format

Single Record

{
    "CompanyId": "ACME",
    "CustomerId": 10,
    "CustomerName": "ABC Supply Company",
    "SalesrepId": "1100",
    "CreditStatus": "GOOD",
    "UserDefinedFields": {},
    "ObjectName": "customer"
}

Collection (List/Query)

[
    {
        "CompanyId": "ACME",
        "CustomerId": 10,
        "CustomerName": "ABC Supply Company"
    },
    {
        "CompanyId": "ACME",
        "CustomerId": 20,
        "CustomerName": "ABC Supply Company"
    }
]

Error Response

{
    "DateTimeStamp": "2026-02-11T15:30:00",
    "ErrorMessage": "Your query did not yield any results. No resources found for query string \"GetById 100198\".",
    "ErrorType": "ResourceNotFoundException",
    "HostName": "P21SERVER",
    "InnerException": null,
    "LogId": "...",
    "StackTrace": "...",
    "UserId": "api_user"
}

Content Types

Both JSON and XML are supported. Set via the Accept header:

Accept: application/json
Accept: application/xml

XML response example (ping):

<?xml version="1.0"?>
<PingResponse>
    <ResponseMessage>success</ResponseMessage>
</PingResponse>

Code Examples

Setup

import httpx

base_url = "https://play.p21server.com"

# Get token
token_resp = httpx.post(
    f"{base_url}/api/security/token/v2",
    json={"username": "api_user", "password": "password"},
    headers={"Accept": "application/json"},
    verify=False,
)
token = token_resp.json()["AccessToken"]

# Create client (must follow redirects for list endpoints)
client = httpx.Client(
    headers={
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    verify=False,
    follow_redirects=True,
)

using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

var baseUrl = "https://play.p21server.com";

// Get token
var handler = new HttpClientHandler
{
    AllowAutoRedirect = true,
    ServerCertificateCustomValidationCallback = (_, _, _, _) => true
};
var client = new HttpClient(handler) { BaseAddress = new Uri(baseUrl) };
client.DefaultRequestHeaders.Add("Accept", "application/json");

var tokenPayload = JsonConvert.SerializeObject(new
{
    username = "api_user",
    password = "password"
});
var tokenResp = await client.PostAsync(
    "/api/security/token/v2",
    new StringContent(tokenPayload, Encoding.UTF8, "application/json")
);
tokenResp.EnsureSuccessStatusCode();
var tokenJson = JObject.Parse(await tokenResp.Content.ReadAsStringAsync());
var token = tokenJson["AccessToken"]!.ToString();

// Set auth header for all subsequent requests
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");

Health Check

resp = client.get(f"{base_url}/api/entity/customers/ping")
resp.raise_for_status()
print(resp.json())  # {"ResponseMessage": "success"}

var resp = await client.GetAsync("/api/entity/customers/ping");
resp.EnsureSuccessStatusCode();
var json = JObject.Parse(await resp.Content.ReadAsStringAsync());
Console.WriteLine(json);  // {"ResponseMessage": "success"}

Get Single Customer

resp = client.get(f"{base_url}/api/entity/customers/ACME_10")
resp.raise_for_status()
customer = resp.json()
print(f"{customer['CustomerId']}: {customer['CustomerName']}")
# 10: ABC Supply Company

var resp = await client.GetAsync("/api/entity/customers/ACME_10");
resp.EnsureSuccessStatusCode();
var customer = JObject.Parse(await resp.Content.ReadAsStringAsync());
Console.WriteLine($"{customer["CustomerId"]}: {customer["CustomerName"]}");
// 10: ABC Supply Company

Get Customer with Extended Properties

resp = client.get(
    f"{base_url}/api/entity/customers/ACME_10",
    params={"extendedproperties": "CustomerAddress"},
)
resp.raise_for_status()
customer = resp.json()
addr = customer["CustomerAddress"]
print(f"{addr['MailCity']}, {addr['MailState']} {addr['MailPostalCode']}")
# Springfield, IL 62701

var resp = await client.GetAsync(
    "/api/entity/customers/ACME_10?extendedproperties=CustomerAddress"
);
resp.EnsureSuccessStatusCode();
var customer = JObject.Parse(await resp.Content.ReadAsStringAsync());
var addr = customer["CustomerAddress"]!;
Console.WriteLine($"{addr["MailCity"]}, {addr["MailState"]} {addr["MailPostalCode"]}");
// Springfield, IL 62701

Query Customers

resp = client.get(
    f"{base_url}/api/entity/customers/",
    params={"$query": "startswith(CustomerName, 'ABC')"},
)
resp.raise_for_status()
customers = resp.json()
print(f"Found {len(customers)} customers")
for c in customers:
    print(f"  {c['CompanyId']}_{c['CustomerId']}: {c['CustomerName']}")

var resp = await client.GetAsync(
    "/api/entity/customers/?$query=startswith(CustomerName, 'ABC')"
);
resp.EnsureSuccessStatusCode();
var customers = JArray.Parse(await resp.Content.ReadAsStringAsync());
Console.WriteLine($"Found {customers.Count} customers");
foreach (var c in customers)
{
    Console.WriteLine($"  {c["CompanyId"]}_{c["CustomerId"]}: {c["CustomerName"]}");
}

Get Contact

resp = client.get(f"{base_url}/api/entity/contacts/1")
resp.raise_for_status()
contact = resp.json()
print(f"{contact['FirstName']} {contact['LastName']}")
# John Smith

var resp = await client.GetAsync("/api/entity/contacts/1");
resp.EnsureSuccessStatusCode();
var contact = JObject.Parse(await resp.Content.ReadAsStringAsync());
Console.WriteLine($"{contact["FirstName"]} {contact["LastName"]}");
// John Smith

Create Customer

# Get template first
resp = client.get(f"{base_url}/api/entity/customers/new")
resp.raise_for_status()
template = resp.json()

# Fill required fields
template["CompanyId"] = "ACME"
template["CustomerName"] = "New Customer Inc."
template["SalesrepId"] = "1100"
template["TermsId"] = "1"

# Create (POST without CustomerId = insert)
resp = client.post(
    f"{base_url}/api/entity/customers",
    json=template,
)
resp.raise_for_status()

// Get template first
var resp = await client.GetAsync("/api/entity/customers/new");
resp.EnsureSuccessStatusCode();
var template = JObject.Parse(await resp.Content.ReadAsStringAsync());

// Fill required fields
template["CompanyId"] = "ACME";
template["CustomerName"] = "New Customer Inc.";
template["SalesrepId"] = "1100";
template["TermsId"] = "1";

// Create (POST without CustomerId = insert)
resp = await client.PostAsync(
    "/api/entity/customers",
    new StringContent(template.ToString(), Encoding.UTF8, "application/json")
);
resp.EnsureSuccessStatusCode();

Update Customer

resp = client.put(
    f"{base_url}/api/entity/customers/ACME_10",
    json={
        "CompanyId": "ACME",
        "CustomerId": 10,
        "CustomerName": "Updated Customer Name",
    },
)
resp.raise_for_status()

var payload = new JObject
{
    ["CompanyId"] = "ACME",
    ["CustomerId"] = 10,
    ["CustomerName"] = "Updated Customer Name"
};
var resp = await client.PutAsync(
    "/api/entity/customers/ACME_10",
    new StringContent(payload.ToString(), Encoding.UTF8, "application/json")
);
resp.EnsureSuccessStatusCode();

Template Fields (Complete Reference)

Every field for each entity is listed below, sourced directly from the /new template endpoints. Extended properties (nested objects) are listed separately from data fields.

Customer Template (102 fields)

Complete field list from GET /api/entity/customers/new:

Extended Properties (null by default, populate via extendedproperties parameter):

Data Fields:

Vendor Template (50 fields)

Complete field list from GET /api/entity/vendors/new:

Extended Properties (null by default, populate via extendedproperties parameter):

Data Fields:

Contact Template (40 fields)

Complete field list from GET /api/entity/contacts/new:

Extended Properties (null by default, populate via extendedproperties parameter):

Data Fields:

Address Fields (27 fields)

Note: The Address resource does not have a /new template endpoint (this is by design, not a bug). The field list below is from an existing address record (GET /api/entity/addresses/10).

Complete field list:

Additional Endpoints

SOAP Endpoints

In addition to the REST endpoints documented above, the Entity API also exposes SOAP web services:

Available for: Customer, Vendor, Contact, Address. Use these if your integration platform prefers SOAP over REST.

Mobile Endpoints

The P21 middleware also exposes mobile-specific entity endpoints with additional entities not available via the standard REST API:

Note: The mobile endpoints are designed for the P21 mobile application. Their request/response format may differ from the REST API. Use with caution for custom integrations.

Endpoint Discovery

You can browse all available Entity API endpoints from the P21 middleware home page:

https://{hostname}/docs/

This lists every registered endpoint including REST, SOAP, and mobile resources.

Error Codes

Log File Locations

When troubleshooting 400/500 errors, check the server-side log files:

Other REST Endpoint Families

The REST API exposes more than /api/entity/ and /api/inventory/parts. Verified against a 25.2 tenant (July 2026):

/api/sales/orders — exists and responds

Writes and the approve action are untested — treat this family as read-verified only until documented further.

Families that 404 on the tested tenant

sales/customers, sales/quotes, sales/invoices, sales/shipments, sales/payments, purchasing/*, ar/*, inventory/items, inventory/lots — all returned 404 on ping. Availability may vary by version; the SOA middleware admin site lists the endpoint families your server actually exposes.

Credit: Felipe Maurer (P21WWUG profile) — surfaced /api/sales/orders and the middleware endpoint listing in this forum topic.

Common Errors

Common Mistakes

1. Wrong URL pattern for the 4 entities - Use /api/entity/customers, NOT /api/sales/customers
2. Simple ID for customers - Use ACME_10, NOT just 10
3. Missing redirect handling - List endpoints return 307, must follow redirect
4. Confusing VendorId with supplier_id - These are different database tables
5. Expecting orders/items at /api/entity/ - Only 4 entities exist there (customers, vendors, contacts, addresses). Inventory uses /api/inventory/parts (Inventory REST API); orders use /api/sales/orders (Other REST Endpoint Families)

Entity API vs Other APIs

Related

• Authentication
• API Selection Guide
• OData API - For read-only queries on any table
• Transaction API - For bulk data operations
• Interactive API - For stateful CRUD with business logic
• Inventory REST API - Inventory CRUD at /api/inventory/parts
• examples/python/entity/ - Test scripts