Opportunity Sync via SOAP API

This post describes how to insert Opportunities into Marketo via the SOAP API and associate them to companies and leads. It starts with an explanation of how this process works and then provides code samples for each of the scenarios.

Table Structure Diagram

First of all, the diagram below describes the table structure. The Id is auto-generated on creation of a record (sequential number). The field in bold are required: only Opportunity Person Role has required fields. The fields in parenthesis are optional and so are the connections with a dotted line.

Basic Opportunity Insertion

You first insert the Opportunity, and then the Opportunity Person Role, which links the Opportunity to the Lead(s). For this example, well use the Lead Id and the Opportunity Id to specify the Opportunity Person Role. You get the Opportunity Id in the SOAP Response when creating the Opportunity. The Lead Id is visible on every Lead in the Marketo Lead database.

Company Link

In most cases, you want to link an Opportunity to a Company, in addition to an individual. In Marketo, you can’t access the Company records via the SOAP API, only the Lead records (the Lead records contain the company fields). It is still possible to link Opportunities to a Company by adding a unique Company identifier to each Lead, and using that ID in your Opportunity.

Step 1 is to create a ‘Company Id’ field on the lead record and populate it with a unique identifier, usually from a back-end system. Step 2 is to create a ‘Company Id’

field on the Opportunity: you will have to ask Marketo Support or Consulting to create such a field for you. Then populate this field when creating Opportunities, which connects the Opportunity to the Company.

This is especially important if you use Marketo Revenue Cycle Analytics and you want to use the Opportunity Influence Analyzer, which depends on Company information.

Using External Identifiers

In many cases, you may have your own unique identifiers when integrating with a back-end system. It is possible to use these unique identifiers in Marketo through Foreign keys.

For Leads, you would typically use the Foreign System Person Id (FSPID), which is used instead of the Marketo Id or email address as unique identifier. The FSPID is a hidden system field, which is not visible inside Marketo. If you’re not already doing so, it is necessary for Opportunity sync to also save the FSPID in a custom field, for example “Foreign Id” (you can name the field anything). You can create this field yourself as a Marketo administrator.

For Opportunities, you have Marketo Support create another custom field on Opportunity, for example called “Foreign Id” (you can name it anything). Then populate this field when inserting Opportunities.

Finally, when you create the Opportunity Person Role, you use both foreign keys to specify the link between Leads and Opportunities, instead of using the Marketo IDs. You can also use the foreign keys to update Leads of Opportunities. At this time, it’s not possible to add a foreign key to the Opportunity Person Role records, so you’ll have to use the auto-generated Marketo Id for this (which you get in the SOAP response after creating the Opportunity Person Role).

Code Example

Steps:
1. Insert/update Lead with Foreign Key & Company Id
2. Insert Opportunity with Foreign Key
3. Insert Opportunity Person Role with Foreign Keys

1. SOAP Request – Updating existing Lead with Foreign Key & Company Id

This updates an existing Lead (Marketo Id “6”) with the Foreign Key “12346” and the Account/Company Id “C123”. We are also saving the Foreign Key in a custom field, because we need that for the Opportunity Person Role.

Using a Foreign Key is optional: you can also use the Marketo Id to link this Lead to the Opportunity. Using the Company Id is also optional, but it’s required if you want to use the Opportunity Influence Analyzer in RCA.

Request:

Response:

2. SOAP Request – Opportunity Creation

In this case, 2 custom fields have been created on the Opportunity table:
– opportunityId → holds the Opportunity unique ID
– cAccountFSID → holds the company reference

Instead of specifying your own Opportunity ID, you can also use the Marketo-generated Opportunity ID. In that case you leave out the External Key node. The Company association is also optional, but required if you want to use the Opportunity Influence Analyzer in RCA.

Request:

Response:

3. SOAP Request – Opportunity Person Role

This request will link the Lead to the Opportunity. You can specify multiple links in a single SOAP Request (this example links the Opportunity to only 1 Lead). This uses the foreign keys to specify the link, but in the comments it also shows how to use the actual IDs (in this case: 6 for the Lead Id and 40 for the Opportunity Id).

This “IsPrimary” and “Role” fields are optional.

Request:

Response:

Alternative Approach (Do Step 2 and 3 in One Call)

While you can first insert the opportunity, then the Opportunity Person Role, it’s also possible to do this in one SOAP Call. However, you need to use the Foreign Key for Opportunity (you can’t use the auto-generated Opportunity ID in Opportunity Person Role, because the Opportunity hasn’t been generated yet). Of course, you can also link multiple Leads to this Opportunity in this same API Call (this example links the Opportunity to only 1 Lead).

Request:

Response: