Entity API Overview¶

The Entity API is the primary RESTful CRUD interface for Prophet 21. It provides direct access to P21 business entities — customers, vendors, orders, inventory, accounting records, and more — through a consistent set of HTTP endpoints. For most external integrations, the Entity API is the simplest and most direct path to reading and writing P21 data.

What Is the Entity API¶

• RESTful CRUD — standard GET, POST, PUT operations map to read, create, and update
• Direct entity access — each endpoint maps to a P21 business object (customer, order, vendor, etc.)
• Supports User-Defined Fields (UDFs) — custom fields added to entities appear automatically in the XML response
• XML primary format — all requests and responses use XML by default
• Bearer token authentication — standard OAuth 2.0 bearer tokens

Base URL¶

https://{your-server}/api/entity/

All entity endpoints are relative to this base. Replace {your-server} with your P21 application server hostname or IP.

Standard CRUD Operations¶

Every entity in the Entity API follows the same URL pattern and supports the same set of operations.

Compound Key Format¶

Many P21 entities use a two-part compound key in the URL: {companyId}_{entityId}. The underscore _ is the separator.

GET https://{server}/api/entity/customers/01_C100001
                                          ^^  ^^^^^^^
                                          |   customer_id
                                          company_id

Both parts are required. The company ID is typically 01 for single-company installations.

Always Use /new Before Creating Records¶

The /new endpoint returns a fully-formed blank record with all required fields pre-populated with P21 defaults. This serves three purposes:

1. Populates required defaults — fields like date_created, company_id, and various flags are set by P21 business logic
2. Shows you the complete field structure — you can inspect exactly which fields the entity supports, including UDFs
3. The response object is ready to modify and POST back — take the XML, change what you need, and POST it as-is

GET https://{server}/api/entity/customers/new

The response is a fully valid Customer XML document. Modify the fields you need, then POST the entire document to /entity/customers/.

HTTP Headers¶

All requests to the Entity API require these headers:

Content-Type: application/xml
Accept: application/xml
Authorization: Bearer {token}

For GET requests, Content-Type is not required, but Accept and Authorization always are.

URL Pattern Reference¶

https://{server}/api/entity/{entityName}/{companyId}_{entityId}

Health Check (Ping)¶

Every entity endpoint supports a ping operation that confirms the endpoint is reachable and the service is healthy.

GET https://{server}/api/entity/customers/ping

The response is always:

<PingResponse>
  <ResponseMessage>String content</ResponseMessage>
</PingResponse>

Use this in monitoring scripts and integration startup checks before executing business logic.

User-Defined Fields (UDFs)¶

P21 supports custom UDF fields added to entities through the system administration UI. These fields appear automatically in the XML schema alongside standard fields.

• UDFs are included in both GET responses and the /new template
• They are writable via POST and PUT just like standard fields
• Field name prefixes vary by entity (e.g., ud_ is common but not universal)
• The /new endpoint is the most reliable way to discover available UDFs for an entity

List Operations¶

GET /entity/{entityName}/ returns an ArrayOf{Entity} wrapper:

<ArrayOfCustomer>
  <Customer>
    <company_id>01</company_id>
    <customer_id>C100001</customer_id>
    <!-- ... -->
  </Customer>
  <Customer>
    <company_id>01</company_id>
    <customer_id>C100002</customer_id>
    <!-- ... -->
  </Customer>
</ArrayOfCustomer>

Error Handling¶

Error responses include a body with detail. Always read the response body on non-2xx status codes — P21 typically returns a structured XML error that identifies the failing field or rule.

Common Integration Pattern (C#)¶

public class P21EntityClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;

    public P21EntityClient(HttpClient httpClient, string baseUrl)
    {
        _httpClient = httpClient;
        _baseUrl = baseUrl;
        _httpClient.DefaultRequestHeaders.Accept
            .Add(new MediaTypeWithQualityHeaderValue("application/xml"));
    }

    private void SetAuthHeader(string token)
    {
        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", token);
    }

    private async Task<T> GetNewTemplateAsync<T>(string entityName)
    {
        var response = await _httpClient.GetAsync($"{_baseUrl}/entity/{entityName}/new");
        response.EnsureSuccessStatusCode();
        var xml = await response.Content.ReadAsStringAsync();
        var serializer = new XmlSerializer(typeof(T));
        using var reader = new StringReader(xml);
        return (T)serializer.Deserialize(reader);
    }

    private string SerializeToXml<T>(T obj)
    {
        var serializer = new XmlSerializer(typeof(T));
        using var writer = new StringWriter();
        serializer.Serialize(writer, obj);
        return writer.ToString();
    }
}