# Oracle Eloqua

> Oracle Eloqua is a B2B marketing automation platform. Its public API surface is three REST
> families published under one Oracle-maintained Swagger 2.0 contract: the Application API
> (synchronous asset and data management), the Bulk API (asynchronous high-volume import/export
> through a staging area), and the Reporting API (OData-style analytics queries).

This file was generated by API Evangelist from Oracle's own published documentation and
specification. Oracle does not publish an llms.txt for Eloqua.
Generated: 2026-08-13. Method: generated. Source: apis.yml + repo artifacts + docs.oracle.com.

## Before you call anything: there is no fixed API host

Eloqua runs multiple data centers ("pods": p01, p02, p03, p04, p06, p07, p08). Every tenancy
lives on one of them, and tenancies can move. The base URL must be discovered per instance:

    GET https://login.eloqua.com/id
    Authorization: Basic <base64 of Company\User:password>   (or Bearer <token>)

The response carries `urls.apis.rest.standard` and `urls.apis.rest.bulk`. Cache it for the
session — Oracle throttles /id. On any 401, re-call /id: success means the instance moved and
you should retry at the new base; failure means stop.

## Machine-readable contract

- Swagger 2.0 (Oracle-published): https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/swagger.json
- Local verbatim copy: openapi/eloqua-published-swagger.json
- 459 paths, 649 operations, 365 definitions, 136 tags, info.version 2026.08.07
- Caveat: the spec declares NO securityDefinitions even though every endpoint requires auth,
  carries no response examples, and reuses operationIds (`SearchGETRest20`, `ReadIndividualGETRest20`)
  across dozens of endpoints. Bind tools by path+method, not by operationId.

## Authentication

- OAuth 2.0 (recommended). Authorize: https://login.eloqua.com/auth/oauth2/authorize
  Token: https://login.eloqua.com/auth/oauth2/token
  Grants: authorization_code (preferred), implicit, password. Refresh tokens supported.
- HTTP Basic with `CompanyName\Username` (supported, discouraged by Oracle).
- Scope: exactly one value, `full`, and it is optional. There is no least-privilege scope.
  Effective authorization comes from the Eloqua user's security group, not the token.
- Credentials are minted inside a tenancy: Settings > AppCloud Developer > Create New App.
  There is no developer self-serve signup.
- Docs: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/Authentication.html

## API families

### Application API — /API/REST/1.0/ and /API/REST/2.0/
Synchronous. Asset management (emails, landing pages, forms, campaigns, programs, segments)
and data management (contacts, accounts, custom object data). Not for high volume.
- Pagination: `page` + `count` (count max 1000)
- Filtering: `search={term}{operator}{value}`, operators = != > < >= <=, `*` for partial match
- Sorting: `sort` + `dir`, or `orderBy=createdAt DESC`
- Response shaping: `depth=minimal|partial|complete`

### Bulk API — /api/bulk/2.0/
Asynchronous, three steps: (1) create an export or import DEFINITION with a field map,
(2) move data into the staging area, (3) retrieve or sync it. Poll the sync.
- Pagination: `limit` + `offset`, response carries `count`, `hasMore`, `items`, `totalResults`
- Filtering: `q=<term><operator><value>`, e.g. `name='Email*'`
- Formats: application/json and text/csv (no XML)
- Key operations: PostContactExportIndividual, PostContactImportIndividual,
  PostSyncIndividual, GetSyncIndividual, GetSyncDataQuery, GetSyncLogSearch, GetSyncRejectSearch

### Reporting API — /api/reporting/1.0/
Read-only analytics. OData query conventions: `$select`, `$filter`, `$orderby`, `$top`,
`$skip`, `$count`, `$expand`. Does not support `depth`. May require an Eloqua Analyzer license
(403 "Eloqua Analyzer license is required").

## Runtime semantics an agent must handle

- IDEMPOTENCY: none. No idempotency key, no replay token. Retrying a write can duplicate records.
- RATE LIMITS: 429 "Too Many Requests" is documented. NO rate-limit response headers exist and
  no numeric limits are published. You cannot pace yourself from the response.
- ERRORS: not RFC 9457. A 400 returns `{type, parameter, requirement, value}`. Bulk syncs carry
  84 documented `ELQ-nnnnn` application status codes in logs and rejects.
- 503: temporary. Check Eloqua System Status, retry with increasing delay.
- Content-Type is mandatory on PUT and POST.
- Custom fields are addressed by numeric field id via `fieldValues[]` (Application API) or by
  statement such as `Contact.Field(C_EmailAddress)` (Bulk API). Resolve field ids first.

## Commercial

- No published pricing, no plans, no free tier, no trial, no self-serve signup.
  Access requires an Oracle Eloqua subscription. Contact: https://www.oracle.com/cx/marketing/contact.html

## What Oracle does NOT publish for Eloqua

- No first-party SDK on npm, PyPI, RubyGems, Maven Central, NuGet, Go or Packagist.
  Every client library is community-maintained; the freshest last shipped 2024-01-03.
- No MCP server (hosted or stdio). No A2A agent card. No /.well-known/ document on any host.
- No AsyncAPI, no webhook catalog, no event contract.
- No dated API changelog, no RFC 8594 Sunset/Deprecation headers, no published SLA.
- No sandbox or test-mode environment.

## Documentation

- REST API reference: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/
- All endpoints: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/rest-endpoints.html
- Developer's Guide: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-develop/
- Base URL discovery: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/DeterminingBaseURL.html
- HTTP status codes: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/APIRequests_HTTPStatusCodes.html
- Eloqua status codes: https://docs.oracle.com/en/cloud/saas/marketing/eloqua-rest-api/APIRequests_EloquaStatusCodes.html
- System status: https://community.oracle.com/customerconnect/categories/cx-eloqua-system-status/
- Support: https://support.oracle.com/

## API Evangelist artifacts in this repo

- openapi/eloqua-published-swagger.json — Oracle's published contract, verbatim
- authentication/eloqua-authentication.yml — auth profile
- scopes/eloqua-scopes.yml — the single `full` scope
- conventions/eloqua-conventions.yml — pagination, depth, headers, base-URL resolution
- errors/eloqua-problem-types.yml — HTTP codes, validation types, 84 ELQ codes
- data-model/eloqua-data-model.yml — entity graph
- lifecycle/eloqua-lifecycle.yml — versioning, deprecation, status page
- rate-limits/eloqua-rate-limits.yml — what is and is not published
- conformance/eloqua-conformance.yml — standards assertions with evidence
- mcp/eloqua-mcp.yml — candidate MCP tools (no server exists)
- skills/ — packaged agent skills grounded in real operations