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

  1. Create a new opportunity import definition.
  2. 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)}}"
      },
      "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)}}"
      },
      "identifierFieldName": "OpportunityID",
      "isSyncTriggeredOnImport": false,
      "dataRetentionDuration": "P7D",
      "uri": "/opportunities/imports/24",
      "createdBy": "API.User",
      "createdAt": "2018-02-15T15:25:32.4730364Z",
      "updatedBy": "API.User",
      "updatedAt": "2018-02-15T15:25:32.4730364Z"
    }
  3. Upload data to the definition.
  4. 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
  5. Synchronize the data into Eloqua.
  6. POST /api/bulk/2.0/syncs
    Content-Type: application/json 

    Request body

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

    Response

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

    When the sync is successful, the response will resemble:

    {
        "syncedInstanceUri": "/opportunities/imports/24",
        "syncStartedAt": "2018-02-15T15:04:55.3345307Z",
        "status": "success",
        "createdAt": "2018-02-15T15:04:55.3345307Z",
        "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:

  1. Create a new opportunity contact linkage import definition:
  2. 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"
    }
  3. Upload data to the definition.
  4. 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
  5. Synchronize the data.
  6. 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"
    }

Related

Import data into Eloqua

Eloqua markup language version 3