Epicor Kinetic REST API: v1 vs. v2 explained simply

Key facts

• REST means external programs communicate with Epicor using standard HTTPS requests (GET, POST, PATCH, DELETE).
• Calls must go over HTTPS and return payloads in JSON format.
• OData endpoints support standard query options including $select, $filter, $top, $skip, $orderby, and $count=true.
• Every call executes under the security context of the authenticated Epicor user account.
• In REST v2, every request requires both user authentication (Basic Auth or Bearer/OAuth token) and a valid API Key (sent via the x-api-key HTTP header).

V1 vs. v2 at a glance

Use REST v2 for all new integrations.

What the addresses look like

The first part of the address (server hostname and Epicor instance name) depends on your deployment:

Read customers via OData (v2):

https://{server}/{instance}/api/v2/odata/{CompanyID}/Erp.BO.CustomerSvc/Customers

Read a BAQ (v2):

https://{server}/{instance}/api/v2/odata/{CompanyID}/BaqSvc/{BAQID}/Data

Call an Epicor Function (v2):

https://{server}/{instance}/api/v2/efx/{CompanyID}/{LibraryID}/{FunctionID}

Read customers via OData (v1):

https://{server}/{instance}/api/v1/Erp.BO.CustomerSvc/Customers

(Note: In v1, to target a specific company or plant/site other than the user's default, pass the CallSettings header, for example: CallSettings: {"Company":"EPIC06","Plant":"MfgSys"}.)

Replace {CompanyID}, {BAQID}, {LibraryID}, and {FunctionID} with your own values.

A simple read example with OData pagination

To ask for only the customer ID and name of the first 50 customers, add OData query parameters to the URL:

.../api/v2/odata/{CompanyID}/Erp.BO.CustomerSvc/Customers?$select=CustID,Name&$top=50&$skip=0

Using $select, $filter, $top, and $skip keeps responses small, prevents server memory pressure, and avoids timeouts.

What the HTTP verbs mean

• GET: Read data (OData entities or BaqSvc). Does not modify database records.
• POST: Create a new record via OData, invoke a Business Object custom method, or execute an Epicor Function (EFx). (Note: Updatable BAQs and EFx calls can also use POST/PATCH to modify data.)
• PATCH: Update specific fields on an existing OData record.

DELETE Remove a record.

Authentication and Access Scope in plain terms

Two layers identify and authorize a REST v2 request:

1. The API Key (required in v2). An administrator creates an API Key in API Key Maintenance. You pass this key on every request using the x-api-key HTTP header (or the ?api-key= query parameter where headers are not supported). Each API Key can be tied to an Access Scope (configured in Access Scope Maintenance) that explicitly whitelists which Business Objects, BAQs, and Epicor Function libraries that key is allowed to access.

1. User Credentials. The request also authenticates as an Epicor user account (via OAuth 2.0 / Azure AD / Epicor Identity Provider Bearer token, or Basic Authentication over HTTPS).

Think of it as two locks on the door: the API Key (and its Access Scope) controls what the integration application is allowed to touch, while the User Account controls what that Epicor user has permission to do.

API security good habits

1. Create a dedicated service/integration user account for each external integration rather than sharing a human employee's login.
2. Assign that user only the security groups and company/site access the integration requires.
3. Always attach an Access Scope (in Access Scope Maintenance) to every REST v2 API Key so the key can only call the exact BAQs, Business Objects, or Function libraries needed for that integration.
4. Store API keys and credentials in a secure secrets vault or server environment variables—never in client-side browser JavaScript, Git repositories, or spreadsheets.
5. Always use HTTPS.
6. Rotate or revoke API Keys in API Key Maintenance when a project ends or a vendor changes.
7. Maintain an integration inventory: integration name, owner, API Key ID, Access Scope ID, and service user account.

For reads, prefer a BAQ (BaqSvc)

When an external system only needs to read data, calling a shared BAQ through BaqSvc is almost always faster and cleaner than pulling full Business Object tablesets via OData. A BAQ joins the tables on the SQL server and returns only the exact columns and filtered rows you designed.

For writes, use Business Objects or Epicor Functions

When an external system needs to create or update records, call an Epicor Function (/api/v2/efx/...) or a supported Business Object method so that all Epicor validations, GL triggers, and BPM directives execute properly. Never write directly to Epicor SQL tables.

Common errors and what they usually mean

Good habits for developers

• Always include $select, $filter, and $top/$skip on OData queries so you never pull an entire unfiltered table over REST.
• Use your environment's built-in Swagger UI (/api/help/v2/ and /api/help/v1/) to inspect exact service names, custom method payloads, and OData entity schemas for your exact Epicor release.
• Test all integrations in a pilot environment first, and re-verify after every Kinetic upgrade.

FAQ

What is the difference between Epicor REST API v1 and v2?

REST v2 puts the Company ID directly in the URL path, requires an API Key (passed in the x-api-key header), supports granular Access Scope whitelisting, and adds the /api/v2/efx/ endpoint for calling Epicor Functions. In REST v1, the company is omitted from the URL (or passed via the CallSettings header) and Epicor Functions are not available.

What HTTP header is used for the Epicor REST API Key?

Pass the API Key in the x-api-key request header.

Why am I getting a 403 Forbidden error in REST v2 even with a Security Manager account?

In REST v2, a 403 Forbidden error usually means the API Key you are using is restricted by an Access Scope (in Access Scope Maintenance) that does not include the Business Object, BAQ, or Epicor Function library you are calling—or, for an Epicor Function, the library has not been authorized for that company in Epicor Functions Maintenance.

Where do I find the Epicor REST API Swagger documentation?

Browse to https://{your-server}/{your-instance}/api/help/v2/ (or /api/help/v1/) and sign in with an authorized Epicor account.

References

Cross-check against official Epicor documentation matching your release and hosting model:

• Epicor Kinetic help: REST API v1 and v2 Implementation Guide
• Epicor Kinetic help: API Key Maintenance and Access Scope Maintenance
• Epicor Kinetic help: Epicor Functions Maintenance