← Back to blog

Oracle erpintegrations REST API: Submit ESS Jobs and Upload FBDI Files

By Mostafa Mansour 7 min read Oracle FusionREST APIerpintegrationsESS JobsFBDI

If you need to run a scheduled process in Oracle Fusion from outside the application — kick off an import, submit a report, load an FBDI file — the answer is almost always one endpoint: erpintegrations. It is the REST wrapper around the old ErpIntegrationService SOAP service, and it handles ESS job submission, job status, file upload to UCM, and the whole bulk-import flow. It is also one of the strangest REST endpoints in Fusion, and the Customer Connect forums are full of the same three questions about it. This guide answers them with working examples.

All examples use an anonymized pod (acme.fa.us2.oraclecloud.com) and placeholder data — swap in your own values.

Where it lives and why it looks odd

The endpoint sits under the FSCM base URL even when the job you are running belongs to another product family:

https://acme.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations

Unlike a normal Fusion resource, erpintegrations is not a collection of business objects. It is an operation dispatcher: every POST sends an OperationName field, and that field — not the URL — decides what happens. The main operations you will use are submitESSJobRequest, importBulkData, uploadFileToUCM, and downloadESSJobExecutionDetails.

Two things trip up almost everyone on their first call:

  1. The Content-Type header must be application/vnd.oracle.adf.resourceitem+json — plain application/json returns an error on POST.
  2. Unused fields still cause validation failures if you send them empty. Pass "#NULL" for parameters you do not need (for example "ESSParameters": "#NULL"), not an empty string.

Authentication is the same as any other Fusion REST call — Basic Auth over TLS or an OAuth bearer token; our authentication guide covers the options. The calling user needs the duty roles for the ESS job being submitted, not just API access: a 403 here is a security setup issue, not an API one.

Submit an ESS job

The most common use case — run a scheduled process by its package and definition name:

curl -u '[email protected]:********' \
  -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json' \
  -X POST \
  'https://acme.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations' \
  -d '{
    "OperationName": "submitESSJobRequest",
    "JobPackageName": "oracle/apps/ess/financials/generalLedger/programs/common",
    "JobDefName": "JournalImportLauncher",
    "ESSParameters": "1061,Balance Transfer,101,ALL,N,N,N"
  }'

The response echoes your request item back with one field you care about — ReqstId, the ESS request ID:

{
  "OperationName": "submitESSJobRequest",
  "JobPackageName": "oracle/apps/ess/financials/generalLedger/programs/common",
  "JobDefName": "JournalImportLauncher",
  "ReqstId": "100001",
  "RequestStatus": null
}

Notes that answer the recurring forum questions:

Check job status with the ESSJobStatusRF finder

erpintegrations exposes six finders in the spec; the one you want for polling is ESSJobStatusRF, which takes the request ID returned above:

curl -u '[email protected]:********' \
  'https://acme.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=100001&onlyData=true'

{
  "items": [
    {
      "OperationName": "getESSJobStatus",
      "ReqstId": "100001",
      "RequestStatus": "SUCCEEDED"
    }
  ]
}

Poll until RequestStatus leaves the in-flight states (WAIT, READY, RUNNING) and lands on a terminal one (SUCCEEDED, ERROR, WARNING, CANCELED). If you would rather not poll at all, pass a CallbackURL in the original submission and Fusion calls you back when the job completes — the callback endpoint must be reachable from the pod and able to accept the notification payload.

For execution details and log output, ESSExecutionDetailsRF and ESSJobExecutionDetailsRF return the child request tree and log document IDs for a request — useful when an import job spawns sub-requests and you need to know which one failed. (Finder syntax in general — bind variables, chaining with other parameters — is covered in our finders guide.)

The one-call FBDI flow: importBulkData

The classic FBDI dance is: upload the ZIP to UCM, then submit the interface loader job, then submit the import job. importBulkData collapses all of it into a single POST — file content goes in base64, and the JobName + ParameterList fields describe the import job to run after the load:

curl -u '[email protected]:********' \
  -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json' \
  -X POST \
  'https://acme.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations' \
  -d '{
    "OperationName": "importBulkData",
    "DocumentContent": "UEsDBBQAAAAIA...base64 of your FBDI zip...",
    "ContentType": "zip",
    "FileName": "apinvoiceimport.zip",
    "DocumentAccount": "fin$/payables$/import$",
    "JobName": "oracle/apps/ess/financials/payables/invoices/transactions,APXIIMPT",
    "ParameterList": "#NULL,300000001234567,#NULL,#NULL,#NULL,#NULL,N,#NULL,#NULL"
  }'

The response returns a LoadRequestId — the request ID of the load process; the import job it launches shows up as a child request (that is where ESSJobExecutionDetailsRF earns its keep). Watch the two fields people mix up:

If you only want the file in UCM without triggering an import — for example, staging several files before one load — use "OperationName": "uploadFileToUCM" with the same DocumentContent, FileName, and DocumentAccount fields; it returns a DocumentId you can reference later.

erpintegrations vs. the newer scheduler API

Since release 23B, Fusion also exposes a dedicated Enterprise Scheduler REST API at /ess/rest/scheduler/v1/requests/, which supports proper job scheduling, holds, cancellation, and job sets. Rule of thumb: if your flow involves files and FBDI, stay on erpintegrations — the file operations only exist there. If you are purely orchestrating scheduled processes and need job-set support or recurrence, the scheduler API is the more capable tool. Many integrations use both.

Troubleshooting quick hits

Seeing the full endpoint surface

Everything above uses fields and finders straight from the Oracle spec — erpintegrations declares 21 response fields and 6 finders, and knowing they exist is most of the battle. You can browse the full field list, operators, and finder set on our erpintegrations reference page, generated from the real spec data, alongside the rest of the endpoint reference. For the wider FSCM surface — invoices, payments, expenses — start with the FSCM REST API guide.

This post is part of our complete Oracle Fusion API guide — pillars, base URLs, authentication, q filters, finders, and common errors in one place.