Epicor Prophet 21

Description

Epicor Prophet 21 (P21) is a cloud-enabled ERP solution built for wholesale distributors, combining distribution-specific functionality with inventory, order management, and financials in one system.

API documentation

API documentation for Epicor Prophet 21 (used to build this connector) is available via the P21 middleware site for your tenant - for example:

https://<your-p21-host>/docs/home.aspx

The middleware site is the working entry point for API discovery:

Page

Path

Used for

API Reference

/docs/home.aspx

Browse operations, examples, request/response schemas, and enumerated values.

Transaction API Service Explorer

via API Reference

Browse available service names and inspect the transaction surface.

API Console

/docs/console.aspx

Create and manage Authorized API Consumers (consumer label, scope, access type, token expiry).

The middleware API Reference shows a broad API surface, however your tenant's consumer scope, object exposure, and service definitions control what an integration can actually call. Always validate against the target tenant before building production mappings.

Authentication

When adding connector instances for Epicor Prophet 21, the following authentication methods are supported:

Username & password authentication
Consumer key authentication

Both methods authenticate against the same P21 token endpoint (POST /api/security/token/v2) and return a bearer token, which Patchworks manages automatically. The only difference is how the endpoint authenticates the caller:

Connection model

Request fields

Use when

Username & password

UserName and Password (ExpiresSeconds optional)

A P21 user credential is available and the connection should run in that user's context.

Consumer key

ClientSecret, GrantType (client_credentials), and UserName (ExpiresSeconds optional)

A service-style connection should use the generated secret from Authorized API Consumers instead of a P21 password.

Username & password authentication

When a user chooses to add a connector instance using username & password authentication, the credentials below are prompted:

Credential

Required?

Notes

URL

Yes

The base URL of your P21 middleware host - for example: https://mycompany.epicorsaas.com

username

Yes

A P21 user. The connection runs in this user's context, so ensure the user has the permissions needed for your integrations.

password

Yes

The password for the P21 user above.

URL

The URL is the host you use to access the P21 middleware site - everything up to (but not including) /docs/home.aspx. If in doubt, your Epicor administrator or partner can confirm the correct host for your tenant.

Username & password

We recommend creating a dedicated P21 user for Patchworks (e.g. named patchworks) rather than using a personal login. This keeps API activity clearly attributable and avoids disruption if a member of staff leaves or changes their password.

Patchworks handles token creation and refresh automatically, but for reference (or testing in Postman), the underlying call is:

POST {p21Base}/api/security/token/v2
Content-Type: application/json
Accept: application/json

{
  "UserName": "<P21 username>",
  "Password": "<P21 password>",
  "ExpiresSeconds": 3600
}

A successful response contains the access token and its context:

{
  "AccessToken": "<token>",
  "TokenType": "Bearer",
  "ExpiresIn": 3600,
  "Scope": "<scope returned by tenant>",
  "UserName": "<P21 username>"
}

All subsequent calls send the token in the Authorization header:

Authorization: Bearer <AccessToken>
Accept: application/json

Consumer key authentication

When a user chooses to add a connector instance using consumer key authentication, the credentials below are prompted:

Credential

Required?

Notes

URL

Yes

The base URL of your P21 middleware host - for example: https://mycompany.epicorsaas.com

username

Yes

The P21 user associated with the API consumer.

client secret

Yes

The generated secret from an Authorized API Consumer, created in the P21 API Console.

Client secret

To obtain the client secret required for Patchworks to access your Prophet 21 data, you must create an Authorized API Consumer. To do this, follow the steps below.

Step 1 Log into your P21 middleware site and open the API Console (/docs/console.aspx).

Step 2 Locate the Authorized API Consumers section.

Step 3 Enter a descriptive consumer label - we suggest setting this to 'Patchworks'.

Step 4 Enter the API scope needed for your integrations - see the additional setup tab for scope guidance.

Step 5 Select the service consumer type (for a non-interactive connection) and select SDK access if your integrations will use the transaction (/p21sdk) surface.

Step 6 Choose an appropriate token expiry.

Step 7 Click add consumer and copy the generated secret - add this to your password manager, ready for use in your Patchworks setup.

The generated secret is only displayed once. If the value is lost, rotate or recreate the consumer - don't rely on recovering it from P21.

Patchworks handles token creation and refresh automatically, but for reference (or testing in Postman), the underlying call is:

POST {p21Base}/api/security/token/v2
Content-Type: application/json
Accept: application/json

{
  "ClientSecret": "<generated consumer key>",
  "GrantType": "client_credentials",
  "UserName": "<P21 username>",
  "ExpiresSeconds": 3600
}

The response and Authorization: Bearer <AccessToken> header usage are identical to username & password authentication.

The v2 token schema also exposes fields such as AppKey, ConsumerKey, and Scope. The two connection models above are the confirmed patterns for this connector - scope is normally configured on the consumer in the API Console rather than supplied in the token body.

Scopes

The scope configured on your Authorized API Consumer controls which P21 API surfaces the connection can access:

Target surface

Scope example

Notes

Transaction API and SDK

/api;/p21sdk

Requires SDK access to be selected on the consumer.

Data Services OData

/odata:<comma-separated object list>

Confirm the specific table and view names exposed to the consumer.

Other API routes

/api

Confirm whether your target routes require this broader scope.

Your tenant's consumer scope and object exposure determine what Patchworks can call - if requests fail with authorisation errors, check the consumer configuration in the API Console first.

Making API calls

Prophet 21 exposes several API surfaces. As a general rule: use the Transaction API for business writes, OData for reads and searches, and the Entity or Inventory REST routes only when their resource contracts fit the operation.

Surface

What it is

Best fit

Base path

Transaction API

Service and transaction operations that apply P21 business rules

Creates, updates, multi-row workflows, and operations that must behave like P21

{uiBase}/api/v2

Data Services OData

OData access to exposed tables and views

Read and search operations, lightweight synchronisation, and reporting data

{p21Base}/odataservice/odata

Entity API

Simple entity-oriented routes for selected resources

Straightforward customer, vendor, contact, or address operations

{p21Base}/api/entity

Inventory REST API

Direct item and inventory-resource operations

Create, read, update, availability, and pricing operations for items

{p21Base}/api/inventory/v2/parts

Where {p21Base} is your middleware host (as entered in the connector instance URL) and {uiBase} is the transaction host resolved via the router - see below.

Transaction API

The Transaction API exposes P21 service operations. Each service has a name, a definition, and a transaction payload. The service definition is the source of truth for data element names, key fields, field names, and valid values.

Transaction API calls use a UI base URL which may differ from the middleware host. Resolve it via the router:

GET {p21Base}/api/ui/router/v1/?urlType=external

Use the URL returned by this router as {uiBase} for all transaction calls. Don't assume the middleware host is the correct transaction host for every environment.

Purpose

Method and route

Result

List services

GET {uiBase}/api/v2/services

Returns service names such as Customer, Order, Vendor, and other tenant services.

Get definition

GET {uiBase}/api/v2/definition/{ServiceName}

Returns the data elements, keys, fields, and valid values needed to construct a request.

Get defaults

GET {uiBase}/api/v2/defaults/{ServiceName}

Returns service defaults where supported.

Get basics

GET {uiBase}/api/v2/basics/{ServiceName}

Returns basic service metadata where supported.

POST {uiBase}/api/v2/transaction
Content-Type: application/json
Authorization: Bearer <AccessToken>

{
  "Name": "<exact service name>",
  "UseCodeValues": false,
  "Transactions": [
    {
      "Status": "New",
      "DataElements": [
        {
          "Name": "<exact data element from definition>",
          "Type": "Form",
          "Keys": [],
          "Rows": [
            {
              "Edits": [
                {"Name": "<exact field name>", "Value": "<value>"}
              ],
              "RelativeDateEdits": []
            }
          ]
        }
      ]
    }
  ]
}

This body is a request shape, not a universal service payload. Replace every placeholder with the names and structure returned by the selected service definition. A successful HTTP response does not by itself prove that the business transaction succeeded - inspect the transaction status and response details.

POST {uiBase}/api/v2/transaction/get
Content-Type: application/json
Authorization: Bearer <AccessToken>

{
  "ServiceName": "<exact service name>",
  "TransactionStates": [
    {
      "DataElementName": "<exact data element>",
      "Keys": [
        {
          "Name": "<key field>",
          "Value": "<key value>"
        }
      ]
    }
  ]
}

Example: create an item with the Item service

The example below creates an item using the Item service. Retrieve the live Item definition first and confirm that the data element names, field names, and accepted values match the target tenant.

POST {uiBase}/api/v2/transaction
Content-Type: application/json
Authorization: Bearer <AccessToken>

{
  "Name": "Item",
  "UseCodeValues": false,
  "Transactions": [
    {
      "Status": "New",
      "DataElements": [
        {
          "Name": "TABPAGE_1.tp_1_dw_1",
          "Type": "Form",
          "Rows": [
            {
              "Edits": [
                {"Name": "item_id", "Value": "5056854205639"},
                {"Name": "short_code", "Value": "Armorduct Pre-Galvanised Light"},
                {"Name": "extended_desc", "Value": "The Armorduct Pre-Galvanised Lighting Trunking Horizontal 90 Deg Bend has built-in integrated couplers so no need to order separate parts"}
              ]
            }
          ]
        },
        {
          "Name": "TABPAGE_2.tp_2_dw_2",
          "Type": "List",
          "Rows": [
            {
              "Edits": [
                {"Name": "unit_of_measure", "Value": "Unit"}
              ]
            }
          ]
        },
        {
          "Name": "TABPAGE_7.tp_7_dw_7",
          "Type": "Form",
          "Rows": [
            {
              "Edits": [
                {"Name": "supplier_name", "Value": "Armorduct Systems Ltd"},
                {"Name": "upc_code", "Value": "A2WC55"}
              ]
            }
          ]
        }
      ]
    }
  ]
}

Verify the result. Inspect the transaction response and status before treating the item as created, then retrieve the item through a read route (OData or the Inventory REST API) to confirm the fields that actually landed. Don't resubmit the create request blindly if the response is ambiguous - first check whether the item_id already exists.

Example: read an item back

POST {uiBase}/api/v2/transaction/get
Content-Type: application/json
Authorization: Bearer <AccessToken>

{
  "ServiceName": "Item",
  "TransactionStates": [
    {
      "DataElementName": "TABPAGE_1.tp_1_dw_1",
      "Keys": [
        {
          "Name": "item_id",
          "Value": "5056854205639"
        }
      ]
    }
  ]
}

Data Services OData

Data Services exposes OData entity sets for tables and views that the tenant has made available. A view can join, calculate, filter, or reshape data, so a view with a similar name to a table should not be treated as an identical replacement.

Discover the exposed schema - the $metadata responses are the authoritative catalogue of entity sets and fields available to the current connection:

GET {p21Base}/odataservice/odata/table/$metadata
GET {p21Base}/odataservice/odata/view/$metadata

Query a table or view:

GET {p21Base}/odataservice/odata/table/<table_name>?$top=10
GET {p21Base}/odataservice/odata/view/<view_name>?$top=10

...and with server-side selection, filtering, ordering, and paging:

GET {p21Base}/odataservice/odata/view/<view_name>?$select=<field1>,<field2>&$filter=<field> eq '<value>'&$orderby=<field>&$top=50&$skip=0

Use $select to request only the fields your integration needs, and $filter, $orderby, $top, and $skip for bounded, server-side reads. Treat OData as read-oriented - use the Transaction API, Entity API, or Inventory REST API for writes.

Entity API

The Entity API provides a narrower, entity-oriented interface for selected resources. It's useful for simple record operations, but shouldn't replace a transaction service when the operation requires P21 business rules, related records, or multi-step processing.

Customer route examples:

Purpose

Method and route

Notes

Health check

GET {p21Base}/api/entity/customers/ping

Use as a first route test if enabled in the tenant.

New record template

GET {p21Base}/api/entity/customers/new

Use the returned shape as the create or update template.

Get one

GET {p21Base}/api/entity/customers/<CompanyId>_<CustomerId>

Use the composite identifier returned by the API.

Search collection

GET {p21Base}/api/entity/customers/?$query=<query>

Entity query syntax differs from OData $filter.

Create

POST {p21Base}/api/entity/customers

Build the body from the current /new response.

Update

PUT {p21Base}/api/entity/customers/<CompanyId>_<CustomerId>

Use the exact entity key and current payload shape.

Equivalent route families may exist for vendors, contacts, and addresses - confirm the resource, field shape, and supported methods in the target tenant before committing to this API.

Inventory REST API

The API Reference lists item operations under /api/inventory/v2/parts - a separate, item-specific REST route family from the generic /api/entity resources. Use it when direct item CRUD, availability, or pricing operations are a better fit than a service transaction.

Purpose

Method and route

Notes

Health check

GET {p21Base}/api/inventory/v2/parts/ping

Confirms that the item service is available.

Get an item

GET {p21Base}/api/inventory/v2/parts/{ITEMID}

Returns the item resource for the supplied item ID.

Create an item

POST {p21Base}/api/inventory/v2/parts

CreatePart - use the request schema for required fields.

Update an item

PUT {p21Base}/api/inventory/v2/parts/{ITEMID}

UpdatePart - use the current resource shape.

Example create request (retrieve the full schema from the CreatePart operation page before sending):

POST {p21Base}/api/inventory/v2/parts
Content-Type: application/json
Authorization: Bearer <AccessToken>

{
  "ItemId": "5056854205639",
  "ItemDesc": "Armorduct Pre-Galvanised Light",
  "ShortCode": "Armorduct Pre-Galvanised Light",
  "ExtendedDesc": "The Armorduct Pre-Galvanised Lighting Trunking Horizontal 90 Deg Bend has built-in integrated couplers so no need to order separate parts",
  "DefaultSellingUnit": "Unit"
}

First connection test

A short, low-risk discovery sequence for validating a new connection:

Create a token with the selected authentication method.
Resolve the transaction UI base URL through the router.
List services and retrieve one service definition.
Retrieve the OData table and view $metadata documents.
Call an Entity API /new route, or the Inventory REST ping/item route, if that resource is in scope.
Test a document metadata or generation request only after the report or form identifier is known.

PreviousEmarsys pre request script

NextErgonode (prebuilt connector)

Last updated 11 days ago

Was this helpful?