I freely admit this is an esoteric topic, but trust me when I tell you when you need to use it, it's best not to mess it up. The use case is as follows.. suppose you have customers that might exist in some home grown external system with a unique PID (Person ID) that is not the marketo ID, and your business depends on that being unique. In addition, imagine some people in your database may not have emails (I know, I know, but this happens). Now imagine that you can have duplicate emails in Marketo.. but youll never have a duplicate PID.
An example would be when a caretake signs up for an account for someone else (Im leaving that intentionally vague).
In such a case you need to upsert data into Marketo, but you may or may not have email.. and you definitely dont have a Marketo ID. If you're using REST, its not a problem as you can specify a non email dedupe field.. but if you're using SOAP.. its not that simple. In that case you might consider using the "Foreign System ID".
Wait.. the Foreign System what?
It's true, this exists, and its documented, if rarely used, and its important you use it correctly. In the above use case you'd use the following two versions of an input XML to upsert a lead into Marketo.
In my humble opinion, Case 1 is more insteresting... because you're passing in the MarketoID and UPDATING the Foreign System Person ID.
Case 1: NO Email
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mkt="http://www.marketo.com/mktows/">
<soapenv:Header>
<mkt:AuthenticationHeader>
<mktowsUserId>${#TestCase#userid}</mktowsUserId>
<requestSignature>${#TestCase#signature}</requestSignature>
<requestTimestamp>${#TestCase#timestamp}</requestTimestamp>
</mkt:AuthenticationHeader>
</soapenv:Header>
<soapenv:Body>
<mkt:paramsSyncMultipleLeads>
<leadRecordList>
<leadRecord>
<Id>3767415</Id>
<ForeignSysPersonId>DEF1234</ForeignSysPersonId>
<ForeignSysType>CUSTOM</ForeignSysType>
<leadAttributeList>
<attribute>
<attrName>FirstName</attrName>
<attrValue>Ben</attrValue>
</attribute>
</leadAttributeList>
</leadRecord>
</leadRecordList>
<dedupEnabled>TRUE</dedupEnabled>
</mkt:paramsSyncMultipleLeads>
</soapenv:Body>
</soapenv:Envelope>
Case 2: With Email
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mkt="http://www.marketo.com/mktows/">
<soapenv:Header>
<mkt:AuthenticationHeader>
<mktowsUserId>${#TestCase#userid}</mktowsUserId>
<requestSignature>${#TestCase#signature}</requestSignature>
<requestTimestamp>${#TestCase#timestamp}</requestTimestamp>
</mkt:AuthenticationHeader>
</soapenv:Header>
<soapenv:Body>
<mkt:paramsSyncMultipleLeads>
<leadRecordList>
<leadRecord>
<ForeignSysPersonId>ABC123</ForeignSysPersonId>
<ForeignSysType>CUSTOM</ForeignSysType>
<leadAttributeList>
<attribute>
<attrName>FirstName</attrName>
<attrValue>Alicia</attrValue>
</attribute>
<attribute>
<attrName>Email</attrName>
<attrValue>Alicia@Test.com</attrValue>
</attribute>
</leadAttributeList>
</leadRecord>
</leadRecordList>
<dedupEnabled>TRUE</dedupEnabled>
</mkt:paramsSyncMultipleLeads>
</soapenv:Body>
</soapenv:Envelope>
The key it turns out is the ForeignSystemType. In order to properly upsert the lead, you NEED to tell marketo what the ForeignSystemPersonID is.. as well as the ForeignSystemType!
.png)