Using the opportunities endpoints

The opportunities API endpoints enable developers to import opportunities into Eloqua's opportunity object, and then link the opportunities directly to contacts or via accounts by linking the opportunity to all contacts linked at the indicated account.

The opportunities endpoints are similar to other Bulk API endpoints, the differentiator for opportunities is that you need to upload opportunities, and then do a separate import to link opportunities to contacts. This tutorial will walk through the steps needed to import opportunities and link to contacts. For information about the endpoints, see the reference documentation.

Importing opportunities

Required fields and limitations

The following fields are required in the request body.

{{Opportunity.Id}}
{{Opportunity.Field(Name)}}
{{Opportunity.Field(Stage)}}
{{Opportunity.Field(Amount)}}
identifierFieldName

Must contain the {{Opportunity.Id}} field within fields.

To import opportunities

Create a new opportunity import definition.

POST /api/bulk/2.0/opportunities/imports
Content-Type: application/json

Request body

{
  "name": "Opportunity Import",
  "fields": {
    "OpportunityID": "{{Opportunity.Id}}",
    "OpportunityName": "{{Opportunity.Field(Name)}}",
    "AccountName": "{{Opportunity.Field(AccountName)}}",
    "CreatedDate": "{{Opportunity.CreatedAt}}",
    "Amount": "{{Opportunity.Field(Amount)}}",
    "CloseDate": "{{Opportunity.Field(CloseDate)}}",
    "Currency": "{{Opportunity.Field(Currency)}}",
    "ForecastToCloseDate": "{{Opportunity.Field(ForecastToCloseDate)}}",
    "Stage": "{{Opportunity.Field(Stage)}}",
    "Territory": "{{Opportunity.Field(Territory)}}",
    "Owner": "{{Opportunity.Field(Owner)}}",
    "PrimaryCampaignId": "{{Opportunity.Field(PrimaryCampaignId)}}"
  },
  "identifierFieldName": "OpportunityID",
  "isIdentifierFieldCaseSensitive": false
}

Response

{
    "isIdentifierFieldCaseSensitive": false,
    "name": "Opportunity Import",
    "fields": {
        "OpportunityID": "{{Opportunity.Id}}",
        "OpportunityName": "{{Opportunity.Field(Name)}}",
        "AccountName": "{{Opportunity.Field(AccountName)}}",
        "CreatedDate": "{{Opportunity.CreatedAt}}",
        "Amount": "{{Opportunity.Field(Amount)}}",
        "CloseDate": "{{Opportunity.Field(CloseDate)}}",
        "Currency": "{{Opportunity.Field(Currency)}}",
        "ForecastToCloseDate": "{{Opportunity.Field(ForecastToCloseDate)}}",
        "Stage": "{{Opportunity.Field(Stage)}}",
        "Territory": "{{Opportunity.Field(Territory)}}",
        "Owner": "{{Opportunity.Field(Owner)}}",
        "PrimaryCampaignId": "{{Opportunity.Field(PrimaryCampaignId)}}"
    },
    "identifierFieldName": "OpportunityID",
    "isSyncTriggeredOnImport": false,
    "dataRetentionDuration": "P7D",
    "uri": "/opportunities/imports/24",
    "createdBy": "API.User",
    "createdAt": "2022-06-13T14:02:29.6270000Z",
    "updatedBy": "API.User",
    "updatedAt": "2022-06-13T14:02:29.6270000Z"
}

Upload data to the definition.

POST /api/bulk/2.0/opportunities/imports/24/data
Content-Type: application/json

Request body

[
  {
    "OpportunityID": "1",
    "OpportunityName": "ABC Company",
    "AccountName": "ABC",
    "CreatedDate": "2017-10-05 1:15",
    "Amount": "1000000",
    "CloseDate": "",
    "Currency": "USD",
    "ForecastToCloseDate": "",
    "Stage": "Prospecting",
    "Territory": "West"
  },
  {
    "OpportunityID": "2",
    "OpportunityName": "XYZ Company",
    "AccountName": "XYZ",
    "CreatedDate": "2017-10-05 1:25",
    "Amount": "1000000",
    "CloseDate": "",
    "Currency": "USD",
    "ForecastToCloseDate": "",
    "Stage": "Prospecting",
    "Territory": "West"
  }
]

Response

204 No Content

Synchronize the data into Eloqua.

POST /api/bulk/2.0/syncs
Content-Type: application/json

Request body

{
   "syncedInstanceUri": "/opportunities/imports/24"
}

Response

{
   "syncedInstanceUri": "/opportunities/imports/24",
   "status": "pending",
   "createdAt": "2022-06-13T14:02:29.6270000Z",
   "createdBy": "API.User",
   "uri": "/syncs/10"
}

When the sync is successful, the response will resemble:

{
    "syncedInstanceUri": "/opportunities/imports/24",
    "syncStartedAt": "2022-06-13T14:02:29.6270000Z",
    "status": "success",
    "createdAt": "2022-06-13T14:02:29.6270000Z",
    "createdBy": "API.User",
    "uri": "/syncs/10"
}

Linking to contacts

Required fields and limitations

Note the following required fields and limitations when creating an opportunity contact linkage import definition.

The {{Opportunity.Id}} field is required within fields.
At least one contact or account field is required within fields.
There is a maximum of two fields allowed.

To link to contacts:

Create a new opportunity contact linkage import definition:

POST /api/bulk/2.0/opportunities/contacts/imports
Content-Type: application/json

Request body

{
  "name": "Opportunity Contact Linkage Import",
  "fields": {
    "EmailAddress": "{{Opportunity.Contact.Field(C_EmailAddress)}}",
    "OpportunityID": "{{Opportunity.Id}}"
  },
  "linkOpportunitiesCaseSensitiveMatchField": false,
  "linkOpportunitiesCaseSensitiveSourceField": false,
  "linkOpportunitiesEntityType": "Contact",
  "linkOpportunitiesMatchFieldName": "OpportunityID",
  "linkOpportunitiesMultipleSourceMatches": true,
  "linkOpportunitiesSourceField": "EmailAddress"
}

In our import definition, we are stating that we want to link contacts by their email address to specific opportunities, by OpportunityID. For more information about the parameters shown here, see the reference documentation.

Response

{
  "linkOpportunitiesMatchFieldName": "OpportunityID",
  "linkOpportunitiesSourceField": "EmailAddress",
  "linkOpportunitiesEntityType": "Contact",
  "linkOpportunitiesCaseSensitiveSourceField": false,
  "linkOpportunitiesCaseSensitiveMatchField": false,
  "linkOpportunitiesMultipleSourceMatches": true,
  "name": "Opportunity Contact Linkage Import",
  "fields": {
    "EmailAddress": "{{Opportunity.Contact.Field(C_EmailAddress)}}",
    "OpportunityID": "{{Opportunity.Id}}"
  },
  "identifierFieldName": "OpportunityID",
  "isSyncTriggeredOnImport": false,
  "dataRetentionDuration": "P7D",
  "uri": "/opportunities/contacts/imports/23",
  "createdBy": "API.User",
  "createdAt": "2018-02-15T15:03:43.3345307Z",
  "updatedBy": "API.User",
  "updatedAt": "2018-02-15T15:03:43.3345307Z"
}

Upload data to the definition.

POST /api/bulk/2.0/opportunities/contacts/imports/23/data
Content-Type: application/json

Request body

[
  {
    "OpportunityID": "1",
    "EmailAddress": "contact1@abccompany.com"
  },
  {
    "OpportunityID": "2",
    "EmailAddress": "contact2@zyxcompany.com"
  }
]

All of my contacts with the email address contact1@abccompany.com are being linked to the opportunity with OpportunityID #1. And all of my contacts with the email address contact2@zyxcompany.com are being linked to the opportunity with OpportunityID #2.

Response

204 No Content

Synchronize the data.

POST /api/bulk/2.0/syncs
Content-Type: application/json

Request body

{
   "syncedInstanceUri": "/opportunities/contacts/imports/23"
}

Response

{
   "syncedInstanceUri": "/opportunities/contacts/imports/23",
   "status": "pending",
   "createdAt": "2018-02-15T15:04:55.3345307Z",
   "createdBy": "API.User",
   "uri": "/syncs/13"
}

When the sync is successful, the response will resemble:

{
    "syncedInstanceUri": "/opportunities/contacts/imports/23",
    "syncStartedAt": "2018-02-15T15:04:55.3345307Z",
    "status": "success",
    "createdAt": "2018-02-15T15:04:55.3345307Z",
    "createdBy": "API.User",
    "uri": "/syncs/13"
}

Learn more

Import data into Eloqua

Eloqua markup language version 3