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 correct base path is /api/entity/, not /api/sales/ or /api/inventory/.

Overview

The Entity API is a stateless REST API for CRUD (Create, Read, Update, Delete) operations on P21 business objects. It uses domain object models and supports four entities: Customer, Vendor, Contact, and Address.

P21 also provides a separate Inventory REST API at /api/inventory/parts — see Inventory REST API for full documentation.

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/ - No orders, invoices, POs, or other business objects
• Inventory is separate - Lives at /api/inventory/parts, not /api/entity/ (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: Older documentation (including Epicor SDK reference guides) may show category-based URLs like /api/sales/customers or /api/inventory/parts. These do not work as Entity API endpoints. Always use /api/entity/. The Inventory REST API at /api/inventory/parts is a separate API documented in Inventory REST API.

Available Entities

Only four entities are available via the Entity API:

Additionally, the Inventory REST API provides CRUD access to inventory items at /api/inventory/parts.

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, ...)

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, tokens expire after 24 hours.

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: - Locations - Warehouse location stock data - Suppliers - Vendor/supplier information - UnitsOfMeasure - UOM definitions and conversion factors - LocationSuppliers - Supplier-location specific data - Lot - Lot tracking information - LocationMSPs - Location specific pricing - Service - Service related data - ServiceContracts - linked service contracts - Notes - Item notes - MSDS - Material Safety Data Sheets - RestrictedClasses - Class restrictions - AltCodes - Alternate item codes

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>

Python 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,
)

Health Check

resp = client.get(f"{base_url}/api/entity/customers/ping")
resp.raise_for_status()
print(resp.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

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

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']}")

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

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()

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()

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:

Common Errors

Common Mistakes

1. Wrong URL pattern - 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 - Only 4 entities exist at /api/entity/ (customers, vendors, contacts, addresses). Inventory uses /api/inventory/parts (see Inventory REST API)

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
• scripts/entity/ - Test scripts