How to Integrate Bolt.new with Eloqua

Eloqua's API requires your organization's site name (company identifier), a username, a password, and the base URL for your Eloqua instance. These credentials combine to form either a Basic auth header or an OAuth flow. For server-to-server integrations — which is the typical Bolt.new pattern — HTTP Basic auth is the simplest and most direct approach. To find your Eloqua base URL, log into Eloqua and look at the URL in your browser. If it shows secure.eloqua.com, your base URL is https://secure.eloqua.com. Some enterprise installations use custom subdomains. Alternatively, you can use the Eloqua Login Service to discover your instance's URL programmatically: send a GET request to https://login.eloqua.com/id with Basic auth credentials (where the username is formatted as CompanyName\\Username). The response includes the base URLs for REST and Bulk APIs specific to your instance. Your Eloqua credentials follow the format CompanyName\\Username for the username component of Basic auth. This backslash-separated format is specific to Eloqua and different from standard OAuth. In Base64 encoding for the Authorization header, encode the full string CompanyName\\Username:Password as a single Base64 value. For API access, it is best practice to create a dedicated API user in Eloqua rather than using an admin account. Ask your Eloqua administrator to create a user with the 'API' or 'Advanced User' role, which provides the necessary permissions for contact and campaign management without full platform admin rights. Store this user's credentials in .env as ELOQUA_COMPANY, ELOQUA_USERNAME, and ELOQUA_PASSWORD. Never use NEXT_PUBLIC_ prefixes for any of these — they are server-side credentials that must never reach the browser. The Eloqua API has rate limits that vary by plan, typically allowing several hundred requests per minute. For production applications with heavy API usage, implement request caching at the API route level to reduce redundant calls — campaign data and contact lists change infrequently enough that a 5-minute cache is reasonable.

1# .env
2# Eloqua API credentials — all server-side only, never NEXT_PUBLIC_
3# Base URL: check your Eloqua login URL or use the Login Service endpoint
4ELOQUA_BASE_URL=https://secure.eloqua.com
5
6# Eloqua company/site name (the identifier for your organization's Eloqua instance)
7ELOQUA_COMPANY=YourCompanyName
8
9# API user credentials (create a dedicated API user in Eloqua, not an admin account)
10ELOQUA_USERNAME=api.user@yourcompany.com
11ELOQUA_PASSWORD=your_secure_password_here
12
13# Contact list ID for lead capture forms (find in Eloqua → Contacts → Lists)
14ELOQUA_DEFAULT_LIST_ID=1

Create the Eloqua API service module and a Next.js API route for contact management. The service module handles Basic auth header construction and common request patterns, while the API route provides an endpoint for the React frontend to call without directly accessing Eloqua. Eloqua's REST API versioning uses /api/REST/2.0/ as the base path for all current endpoints. Contact operations use the /data/contact endpoint: POST creates a new contact, GET retrieves a contact by ID, PUT updates an existing contact (using the Eloqua contact ID), and DELETE removes a contact. To find or upsert a contact by email address, use GET /data/contacts?search=emailAddress=user@example.com to first check if the contact exists before deciding to create or update. Eloqua contact fields have internal names that differ from their display names in the UI. Standard fields include: firstName, lastName, emailAddress (not 'email'), company (not 'companyName'), title (job title), businessPhone, and address1 through address3. Custom fields created in Eloqua have generated internal names like 'M_Company_Revenue_Range' or names you defined when creating the field. Check your Eloqua administrator or use the API's /assets/contact/fields endpoint to retrieve the internal names for all fields. The Bolt prompt below generates the service module and API route. After generation, test the contact creation endpoint by submitting the lead form in Bolt's preview — outbound HTTP calls to Eloqua's REST API work in the WebContainer since they use standard HTTPS. The 401 error is the most common issue: verify the Base64 encoding of CompanyName\\Username:Password is correct, as the backslash in the company-username separator must be included literally before encoding.

1// lib/eloqua.ts
2function getEloquaAuth(): string {
3  const company = process.env.ELOQUA_COMPANY;
4  const username = process.env.ELOQUA_USERNAME;
5  const password = process.env.ELOQUA_PASSWORD;
6  if (!company || !username || !password) {
7    throw new Error('Eloqua credentials not configured');
8  }
9  // Eloqua Basic auth format: Base64 of 'CompanyName\\Username:Password'
10  return Buffer.from(`${company}\\${username}:${password}`).toString('base64');
11}
12
13const BASE = () => {
14  const url = process.env.ELOQUA_BASE_URL;
15  if (!url) throw new Error('ELOQUA_BASE_URL not configured');
16  return `${url}/api/REST/2.0`;
17};
18
19export interface EloquaContactFields {
20  firstName?: string;
21  lastName?: string;
22  emailAddress?: string;
23  company?: string;
24  title?: string;
25  businessPhone?: string;
26  [key: string]: string | undefined;
27}
28
29async function eloquaFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
30  const res = await fetch(`${BASE()}${path}`, {
31    ...options,
32    headers: {
33      Authorization: `Basic ${getEloquaAuth()}`,
34      'Content-Type': 'application/json',
35      ...options.headers,
36    },
37  });
38
39  if (!res.ok) {
40    const body = await res.text();
41    throw Object.assign(new Error(`Eloqua API error: ${res.status}`), { status: res.status, body });
42  }
43
44  return res.json();
45}
46
47export async function findContactByEmail(email: string) {
48  const encoded = encodeURIComponent(`emailAddress='${email}'`);
49  return eloquaFetch<{ elements: Array<{ id: string; emailAddress: string }> }>(
50    `/data/contacts?search=${encoded}&depth=minimal`
51  );
52}
53
54export async function createContact(fields: EloquaContactFields) {
55  return eloquaFetch('/data/contact', {
56    method: 'POST',
57    body: JSON.stringify(fields),
58  });
59}
60
61export async function updateContact(contactId: string, fields: EloquaContactFields) {
62  return eloquaFetch(`/data/contact/${contactId}`, {
63    method: 'PUT',
64    body: JSON.stringify({ ...fields, id: contactId }),
65  });
66}
67
68export async function addToList(contactId: string, listId: string) {
69  return eloquaFetch(`/data/contact/list/${listId}`, {
70    method: 'POST',
71    body: JSON.stringify({ type: 'Contact', id: contactId }),
72  });
73}

Eloqua's Bulk API is a separate, asynchronous API designed for data operations involving thousands or millions of records — volumes where individual REST API calls would be impractical due to rate limits and response times. The Bulk API uses a three-step pattern: define an export or import job, start a sync to execute the job, and retrieve the results after the sync completes. For a Bolt.new dashboard, the most useful Bulk API operation is exporting contact data for reporting. The export workflow: POST a definition to /api/bulk/2.0/contacts/exports describing which fields to include and any filters (for example, contacts created in the last 30 days). The response includes an export URI. POST to /api/bulk/2.0/syncs to start the export sync, referencing the export URI. Poll GET /api/bulk/2.0/syncs/{syncId}/status until the status changes from 'pending' or 'active' to 'success.' Retrieve the exported data from GET /api/bulk/2.0/contacts/exports/{exportId}/data, which returns paginated JSON records. The Bulk API uses the same Basic auth as the REST API but with a different base path: /api/bulk/2.0/ instead of /api/REST/2.0/. Note that the Bulk API has its own set of field names for exports — they follow an extended naming convention and are retrieved from /api/bulk/2.0/contacts/fields. For large exports, implement server-side polling rather than client-side polling — have the API route poll the sync status with a short delay between checks, then return the complete data when ready. Set a maximum polling timeout (for example, 60 seconds) to prevent hanging requests. Very large exports should use a background job pattern: start the export, return a job ID to the client, and let the client poll a status endpoint.

1// Bulk API export helper — add to lib/eloqua.ts
2const BULK_BASE = () => {
3  const url = process.env.ELOQUA_BASE_URL;
4  if (!url) throw new Error('ELOQUA_BASE_URL not configured');
5  return `${url}/api/bulk/2.0`;
6};
7
8async function bulkFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
9  const res = await fetch(`${BULK_BASE()}${path}`, {
10    ...options,
11    headers: {
12      Authorization: `Basic ${getEloquaAuth()}`,
13      'Content-Type': 'application/json',
14      ...options.headers,
15    },
16  });
17  if (!res.ok) throw new Error(`Bulk API error: ${res.status}`);
18  return res.json();
19}
20
21export async function bulkExportContacts(fields: string[]) {
22  // Step 1: Create export definition
23  const def = await bulkFetch<{ uri: string }>('/contacts/exports', {
24    method: 'POST',
25    body: JSON.stringify({
26      name: 'BoltExport_' + Date.now(),
27      fields: Object.fromEntries(fields.map((f) => [f, `{{Contact.Field(C_${f})}}`])),
28    }),
29  });
30
31  // Step 2: Start sync
32  const sync = await bulkFetch<{ uri: string; syncedInstanceUri: string }>('/syncs', {
33    method: 'POST',
34    body: JSON.stringify({ syncedInstanceUri: def.uri }),
35  });
36
37  // Step 3: Poll for completion
38  const syncId = sync.uri.split('/').pop();
39  let attempts = 0;
40  while (attempts < 20) {
41    await new Promise((r) => setTimeout(r, 3000));
42    const status = await bulkFetch<{ status: string }>(`/syncs/${syncId}`);
43    if (status.status === 'success') break;
44    if (status.status === 'error') throw new Error('Bulk export sync failed');
45    attempts++;
46  }
47
48  // Step 4: Retrieve data
49  const exportId = def.uri.split('/').pop();
50  return bulkFetch<{ items: Record<string, string>[] }>(
51    `/contacts/exports/${exportId}/data?limit=1000`
52  );
53}

If your Bolt.new app needs to access multiple Eloqua customer accounts (not just your own), you need OAuth 2.0 authentication rather than Basic auth. OAuth 2.0 is also required by some Eloqua enterprise configurations that disable Basic auth for security reasons. Eloqua's OAuth 2.0 implementation follows the standard authorization code flow. Register an application in Eloqua's App Cloud Developer portal (appcloud.eloqua.com) to get a client ID and client secret. The authorization URL is https://login.eloqua.com/auth/oauth2/authorize. The token endpoint is https://login.eloqua.com/auth/oauth2/token. Required scopes include 'full' for complete API access or more granular scopes for specific operations. The critical constraint for OAuth 2.0 with Eloqua in Bolt.new is identical to other OAuth providers: the redirect URI must be a stable, publicly accessible URL — meaning your deployed Netlify or Bolt Cloud site, not the Bolt WebContainer preview. The preview uses a dynamic StackBlitz URL that changes between sessions and cannot be registered in the App Cloud Developer portal. Set up the OAuth flow on your deployed site: create an authorization URL endpoint that redirects users to Eloqua's authorize page, handle the callback in a Next.js API route that exchanges the code for tokens, and store the access token securely. Eloqua OAuth access tokens expire after one hour, so implement token refresh using the refresh token returned alongside the access token.

1// app/api/auth/callback/eloqua/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET(request: Request) {
5  const { searchParams } = new URL(request.url);
6  const code = searchParams.get('code');
7  if (!code) {
8    return NextResponse.json({ error: 'Missing authorization code' }, { status: 400 });
9  }
10
11  const clientId = process.env.ELOQUA_CLIENT_ID!;
12  const clientSecret = process.env.ELOQUA_CLIENT_SECRET!;
13  const redirectUri = `${process.env.NEXT_PUBLIC_APP_URL}/api/auth/callback/eloqua`;
14
15  const tokenRes = await fetch('https://login.eloqua.com/auth/oauth2/token', {
16    method: 'POST',
17    headers: {
18      Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`,
19      'Content-Type': 'application/x-www-form-urlencoded',
20    },
21    body: new URLSearchParams({
22      grant_type: 'authorization_code',
23      code,
24      redirect_uri: redirectUri,
25    }),
26  });
27
28  if (!tokenRes.ok) {
29    return NextResponse.json({ error: 'Token exchange failed' }, { status: 400 });
30  }
31
32  const tokens = await tokenRes.json();
33  // Store access_token and refresh_token securely
34  // For single-user setup: copy access_token to ELOQUA_ACCESS_TOKEN in .env
35  console.log('Eloqua OAuth tokens received:', {
36    access_token: tokens.access_token?.substring(0, 10) + '...', // truncated for security
37    expires_in: tokens.expires_in,
38    has_refresh_token: !!tokens.refresh_token,
39  });
40
41  return NextResponse.redirect(new URL('/dashboard', request.url));
42}