Opportunities

Marketo exposes APIs for reading, writing, creating and updating opportunity records. In Marketo, opportunity records are linked to lead and contact records through the intermediate Opportunity Role object, so an opportunity may be linked to many individual leads. Both of these object types are exposed through the API, and like most of the Lead Database object types, they both have a corresponding Describe call, which returns metadata about the object types.

Opportunity APIs are only exposed for subscriptions which do not have a native CRM sync enabled.

The most important fields for this response type are “idField,” “dedupeFields,” and “searchableFields.” idField indicates the primary key for opportunities, marketoGUID. This is a system generated unique key, which can be used for read and update operations, but not for inserts, since it is system managed. The dedupeFields array indicates which fields are valid keys for insert operations; in the case of opportunities, this is only externalOpportunityId. The searchableFields array gives you the set of fields which are valid for querying, externalOpportunityId and marketoGUID.

Query

The pattern for querying opportunities closely follows that of the leads API with the added restriction that the filterType parameter accepts the fields listed in the searchableFields array or of the corresponding describe call, or dedupeFields. Note that if you are using custom opportunity fields, only custom opportunity fields of type String or Integer will be listed in searchableFields array.

You can also include the optional query parameters fields, for returning additional opportunity fields, nextPageToken, for paging through sets larger than the batch size, batchSize, which defaults to and has a maximum of 300.

Create and Update

Opportunities follow the leads API pattern closely, with some restrictions. The values available for action are: createOnly, createOrUpdate, and updateOnly. When using createOnly or createOrUpdate mode, the externalOpportunityId field must be included in each record. For the updateOnly mode, either marketoGUID or externalOpportunityId may be used. The mode defaults to createOrUpdate if unspecified.

The lookupField parameter from the leads API is unavailable, and is superceded by the dedupeBy parameter, which is only valid if action is updateOnly. The values available for dedupeBy are either “dedupeFields” or “idField” which are specified by the describe call as externalOpportunityId and marketoGUID respectively. If dedupeBy is unspecified, it defaults to dedupeFields mode.

You can submit up to 300 records at a time.

Request

1

POST/rest/v1/opportunities.json

Body

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

{

"action":"createOrUpdate",

"dedupeBy":"dedupeFields",

"input":[

{

"externalOpportunityId":"19UYA31581L000000",

"name":"Chairs",

"description":"Chairs",

"amount":"1604.47",

"source":"Inbound Sales Call/Email"

},

{

"externalOpportunityId":"29UYA31581L000000",

"name":"Big Dog Day Care-Phase12",

"description":"Big Dog Day Care-Phase12",

"amount":"1604.47",

"source":"Email"

}

]

}

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"seq":0,

"status":"updated",

"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb"

},

{

"seq":1,

"status":"created",

"marketoGUID":"cff23271-f996-47d7-984f-f2676861b5fb"

}

]

}

The API will respond with the marketoGUID for each record, as well as a status field, indicating the individual success or failure of each record, and an “seq” field which is used to correlate the submitted records, to the order of the response. The number in the field is the index of the record submitted in the request.

Delete

You may delete opportunities by dedupe fields or id field. Specify using the deleteBy parameter with a value of either dedupeFields or idField. If not specified, the default is dedupeFields. The request body contains an input array of opportunities to delete. A maximum of 300 opportunities per call are permitted.

Latest Blog Posts

Keep up with what's new in the developer world

Important Change to Activity Records in Marketo APIs March 1, 2017 Note: This post will be updated to reflect changes made to activity records returned by the API due to migration to new infrastructure.
With the rollout of Marketo’s next-generation Activity Service beginning in Septmeber, we will be unable to enforce the uniqueness or presence of the integer “id” field in activities, data value changes, or lead deletion ... Read More >

Internet of Things for Marketers with IFTTT and Zapier June 20, 2017 The Internet of Things (IoT) is the inter-networking of connected devices, appliances, wearables, vehicles, etc. with embedded electronics, software, sensors, and network connectivity that enable these objects to collect and exchange data with cloud information systems. These technologies are growing and trending so fast that they will impact how we live, how we work and ... Read More >

Spring 2017 Updates June 16, 2017 In the Spring 2017 release, we are adding the ability to bulk extract lead and activity object data asynchronously, and to manipulate named account lists. See the full list of updates below.
Lead Database APIs
Bulk Extract of Leads
New endpoints to support extraction of leads in bulk. Specify record selection criteria using a variety of options. Details can ... Read More >