Opportunity Endpoint Reference

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.



Describing Opportunity records follows the standard pattern for lead database objects.

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.


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.

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.


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.