How-toEpicor KineticREST API / Integration

Epicor Kinetic API Documentation: Where It Lives and How the URLs Work

Question
epicor kinetic api documentation

Also searched as

  • epicor kinetic rest api documentation
  • epicor erp api documentation
  • epicor kinetic api url
  • epicor kinetic sdk

Short answer

Epicor Kinetic documents its REST API on your own server: a Swagger-style help page under /api/help lists every business object, method and field for your exact version. v1 uses /api/v1/ service URLs, v2 uses /api/v2/odata/{Company}/ and adds function (EFx) and BAQ endpoints. There is no separate SDK you must install; most teams call REST or generate a client from the OpenAPI definition.

Applies to: Epicor Kinetic 2021 and later, and Epicor ERP 10.2.x for the v1 pattern; Kinetic cloud and on-prem. Exact page layout varies by release.

Find the docs and make your first call

  1. 1Open https://your-server/your-instance/api/help in a browser. Replace the host and instance with the values from your Kinetic web address. This is the live reference for your version.
  2. 2Pick a business object (for example Erp.BO.PartSvc) and expand a method to see the request body, response shape and field list.
  3. 3Build the base URL. v1 pattern: https://server/instance/api/v1/Erp.BO.PartSvc/Parts. v2 pattern: https://server/instance/api/v2/odata/{Company}/Erp.BO.PartSvc/Parts.
  4. 4Authenticate. Send an API key in the x-api-key header (generate it in API Key maintenance) together with either HTTP Basic credentials or a bearer token, depending on how your environment is configured.
  5. 5Send a simple GET with $top=5 first. If it returns rows, add $filter, $select and $expand.
  6. 6For reports and custom data, call a BAQ through the BaqSvc endpoint or a published function through the efx path instead of stitching several business objects together.
  7. 7Keep the help page open next to the Epicor Help Portal. The portal explains concepts; the /api/help page is the authoritative field and method list.

REST v1 versus REST v2: which to use

v1 exposes the classic business object services (BOs) one method at a time, for example GetByID or GetRows. It is familiar to anyone who has used the old service references and is still common in older integrations.

v2 is OData based. You get standard query options ($filter, $select, $top, $orderby, $expand), the company in the URL, and extra routes for Epicor Functions and BAQs. New integrations should start on v2 unless a vendor tool forces v1.

Both versions enforce the same business logic, security and BPM directives as the client, because they call the same BOs. That is the main reason to prefer the API over writing directly to SQL.

GET https://server/instance/api/v2/odata/EPIC06/Erp.BO.PartSvc/Parts?$top=5&$select=PartNum,PartDescription
x-api-key: <your key>
Authorization: Basic <base64 user:password>
GET https://server/instance/api/v2/odata/EPIC06/BaqSvc/MyBaqId/Data?$top=10

The API URL, per environment

The API URL is simply your application server address plus the instance name plus /api. In cloud tenants the host is the tenant name Epicor gave you; on-prem it is whatever IIS binding you set up for the Kinetic web site.

Check the instance name carefully. A wrong instance gives a 404 that looks like a missing endpoint, while a right instance with a bad key gives a 401 or 403. If you see 401, the existing 401 troubleshooting page covers keys, user permissions and token expiry.

Use a dedicated integration user with a narrow security group, not a named employee. Every call runs with that user's menu security and company access.

Is there a Kinetic SDK?

Epicor does not ask you to install a separate SDK. The practical options are: plain HTTP from any language, a client generated from the OpenAPI/Swagger definition on the help page, or the .NET client assemblies that ship with the Windows client for in-process customization code.

For Power BI, Excel and low-code tools, use BAQs exposed through the BaqSvc endpoint. For integrations that must write data, call the business object method the screen itself uses, so BPMs and validation still fire.

Treat any code sample from the web as version specific. Field names and required parameters change between releases, which is why the on-server help page matters more than a blog post.

Try it here, free

Epicor BAQ OData REST URL Builder

Open full tool

Builds Epicor REST v2 OData URLs and curl commands for BAQs and business object services, with API key header and filters.

Common pitfalls

  • !Using the cloud help page of a different version than your tenant, then sending fields your version does not have.
  • !Skipping the x-api-key header; Basic credentials alone are rejected on environments that require a key.
  • !Pulling large tables with no $top or $select, which times out and loads the server. Page results.
  • !Writing to a table through a BAQ-style shortcut and bypassing BPM validation. Use the BO method.
  • !Hard-coding the company ID; test and production companies differ.

How an ERP-grounded AI assistant handles this

An ERPray style assistant that reads Kinetic through these same APIs (or a read-only BAQ layer) can answer questions in plain language, show the exact OData query it ran and respect the caller's Epicor security. For on-prem Kinetic, the model runs on your own GPUs and the API traffic stays inside your network.

See ERPray

Frequently asked questions

What is the Epicor Kinetic API URL?

It is your Kinetic server address, then the instance name, then /api. For example https://server/instance/api/v2/odata/{Company}/Erp.BO.PartSvc/Parts for the Part service in v2. The matching Swagger-style help is at /api/help on the same server.

Does Epicor publish REST API documentation outside my server?

Epicor Help covers concepts and examples, but the authoritative list of services, methods and fields is the help page generated on your own server because it reflects your version, customizations and enabled modules.

Can I call a BAQ from the REST API?

Yes. Publish the BAQ and call it through the BaqSvc route in v2 with OData query options. This is the simplest way to feed Power BI, Excel or a data pipeline with read-only data.

v1 or v2 for a new integration?

Use v2 for new work. It has OData filtering, function and BAQ routes and is where Epicor is investing. Keep v1 only for existing integrations or tools that cannot speak OData.

Related

How-to

Epicor REST API v2: OData Filter, Select and Expand Examples

Epicor Kinetic REST v2 exposes business objects at /api/v2/odata/{Company}/{Service}/{Entity} and BAQs at /api/v2/odata/{Company}/BaqSvc/{BAQId}/Data. Send an API key in the x-api-key header plus credentials, and use standard OData options: $filter, $select, $top, $skip, $orderby and $expand.

Error fix

Fixing Epicor REST v2 API 401 Unauthorized Errors

A 401 Unauthorized calling Epicor's REST v2 (api/v2/odata) endpoint almost always comes down to one of three things: a missing or wrong x-api-key header, valid credentials but an API key scoped to a different company than the one in the URL, or REST services simply not enabled for that endpoint. Confirm the API key exists and is active in Application Studio (or the classic REST API help page), matches the company segment in the URL, and that the account used for Basic auth or OAuth has the right security group.

Advanced

How to create and call an Epicor Function

Open Function Studio from the main menu (Customization > Function Studio) or from inside a BPM designer's Call Context widget, define a Library and Function with typed inputs/outputs, write the logic in the C# widget, then compile and test with the built-in test harness before calling it from a BPM directive, a dashboard, or another function.

How-to

Fixing a Slow Epicor BAQ (Business Activity Query)

A slow BAQ in Epicor is usually caused by unindexed join columns, a subquery or calculated field forcing a table scan, or the BAQ pulling far more rows than the dashboard actually displays before filtering client-side. Fix it by reading the SQL Server execution plan Epicor generates, moving filters into the BAQ criteria instead of the dashboard filter panel, and replacing subqueries with joins where possible.

Error fix

Fixing Epicor BusinessObjectException: BPM Directive Errors

A BusinessObjectException that says "A Business Process Management (BPM) directive has raised the following error" means a directive on that business object stopped the transaction, either deliberately via a Raise Exception widget or accidentally via an unhandled .NET error in Custom Code. Expand the InnerException on the error dialog to see the real message and the directive name, then open BPM Designer for that object and method to find the widget that fired.

How-to

Epicor MRP Runs but Generates No Suggestions

When Epicor's MRP process completes without a job or purchase suggestion for a part you expect one for, the cause is almost always the part's own configuration (Part Class Type, Make Direct, Non-MRP flag, planning Time Fence) or the demand not being linked in a way MRP recognizes, not a defect in the MRP engine. Work through the part's Planning tab, its safety stock and lead time setup, and the demand source (sales order line status, job material requirement) before assuming the run itself failed.

AI for ERP

AI for Epicor Kinetic, Beyond What Prism Covers

Add AI to Epicor Kinetic beyond Prism: private LLM over BAQs, BPM data, and REST v2, on-prem or private cloud, with honest guidance on when Prism already covers you.

AI for ERP

Private AI for Epicor Kinetic Cloud, Outside the Multi-Tenant Boundary

Run a private LLM on Epicor Kinetic private cloud or Kinetic Cloud data via BAQs, REST v2 and Data Fabric, keeping sensitive manufacturing data off shared AI.

Stuck on Epicor Kinetic?

Talk to engineers who work inside Epicor Kinetic every week, and who build private AI that answers these questions from your own ERP data.

Talk to an ERP engineerBrowse ERP Help
All ERP Help articles

Keep exploring

Free tools

ERP fixes and how-tos

Guides

AI on your ERP

Integrations

Comparisons

Software

TermsEpicor BAQ (Business Activity Query)Epicor BPM (Business Process Management)