This function will insert or update a single lead record. When updating an existing lead, the lead can be identified with one of the following keys:
- Marketo ID
- Foreign system ID (implemented as foreignSysPersonId)
- Marketo Cookie (created by Munchkin JS script)
If an existing match is found, the call will perform an update. If not, it will insert and create a new lead. Anonymous leads can be updated using the Marketo Cookie ID and will become known upon update.
Except for Email, all of these identifiers are treated as unique keys. The Marketo ID takes precedence over all other keys. If both foreignSysPersonId and the Marketo ID are present in the lead record, then the Marketo ID will take precedence and the foreignSysPersonId will be updated for that lead. If the only foreignSysPersonId is given, then it will be used as a unique identifier. If both foreignSysPersonId and Email are present but the Marketo ID is not present, the foreignSysPersonId will take precedence and the Email will be updated for that lead.
Optionally, a Context Header can be specified to name the target workspace.
When Marketo workspaces are enabled and the header is used, the following rules are applied:
- If assignment rules are set and a new lead qualifies for any of the configured rules, then new leads are created in the partition defined by the assignment rule. Otherwise, new leads are created in the primary partition of the named workspace.
- Leads matched by the Marketo Lead ID, a foreign system ID, or a Marketo Cookie, must exist in the primary partition of the named workspace, otherwise an error will be returned
- If an existing lead is matched by email, the named workspace is ignored and the lead is updated in its’ current partition
When Marketo workspaces are enabled and the header is NOT used, the following rules are applied:
- If assignment rules are set and a new lead qualifies for any of the configured rules, then new leads are created in the partition defined by the assignment rule. Otherwise, new leads are created in the primary partition of the “Default” workspace.
- Existing leads are updated in their current partition
If Marketo workspaces are NOT enabled, the target workspace MUST be the “Default” workspace. It is not necessary to pass the header.
Request
Field Name |
Required/Optional |
Description |
---|---|---|
leadRecord->Id | Required – Only when Email or foreignSysPersonId is not present | The Marketo Id of the lead record |
leadRecord->Email | Required – Only when Id or foreignSysPersonId is not present | The email address associated with the lead record |
leadRecord->foreignSysPersonId | Required – Only when Id or Email is not present | The foreign system id associated with the lead record |
leadRecord->foreignSysType | Optional – Only required when foreignSysPersonId is present | The type of foreign system. Possible values: CUSTOM, SFDC, NETSUITE |
leadRecord->leadAttributeList->attribute->attrName | Required | The name of the lead attribute you want to update the value of. |
leadRecord->leadAttributeList->attribute->attrValue | Required | The value you want to set to the lead attribute specificed in attrName. |
returnLead | Required | When true will return the complete updated lead record upon update. |
marketoCookie | Optional | The Munchkin javascript cookie |
Request XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.marketo.com/mktows/"> <SOAP-ENV:Header> <ns1:AuthenticationHeader> <mktowsUserId>bigcorp1_461839624B16E06BA2D663</mktowsUserId> <requestSignature>92f05a7be4838ae1c0e5aafe814891ee72968a08</requestSignature> <requestTimestamp>2013-07-31T12:38:47-07:00</requestTimestamp> </ns1:AuthenticationHeader> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns1:paramsSyncLead> <leadRecord> <Email>t@t.com</Email> <leadAttributeList> <attribute> <attrName>FirstName</attrName> <attrValue>George</attrValue> </attribute> <attribute> <attrName>LastName</attrName> <attrValue>of the Jungle</attrValue> </attribute> </leadAttributeList> </leadRecord> <returnLead>false</returnLead> </ns1:paramsSyncLead> </SOAP-ENV:Body> </SOAP-ENV:Envelope> |
Response XML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://www.marketo.com/mktows/"> <SOAP-ENV:Body> <ns1:successSyncLead> <result> <leadId>1089965</leadId> <syncStatus> <leadId>1089965</leadId> <status>UPDATED</status> <error xsi:nil="true" /> </syncStatus> <leadRecord xsi:nil="true" /> </result> </ns1:successSyncLead> </SOAP-ENV:Body> </SOAP-ENV:Envelope> |
Sample Code – PHP
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
<?php $debug = true; $marketoSoapEndPoint = ""; // CHANGE ME $marketoUserId = ""; // CHANGE ME $marketoSecretKey = ""; // CHANGE ME $marketoNameSpace = "http://www.marketo.com/mktows/"; // Create Signature $dtzObj = new DateTimeZone("America/Los_Angeles"); $dtObj = new DateTime('now', $dtzObj); $timeStamp = $dtObj->format(DATE_W3C); $encryptString = $timeStamp . $marketoUserId; $signature = hash_hmac('sha1', $encryptString, $marketoSecretKey); // Create SOAP Header $attrs = new stdClass(); $attrs->mktowsUserId = $marketoUserId; $attrs->requestSignature = $signature; $attrs->requestTimestamp = $timeStamp; $authHdr = new SoapHeader($marketoNameSpace, 'AuthenticationHeader', $attrs); $options = array("connection_timeout" => 20, "location" => $marketoSoapEndPoint); if ($debug) { $options["trace"] = true; } // Create Request $leadKey = new stdClass(); $leadKey->Email = "george@jungle.com"; // Lead attributes to update $attr1 = new stdClass(); $attr1->attrName = "FirstName"; $attr1->attrValue = "George"; $attr2= new stdClass(); $attr2->attrName = "LastName"; $attr2->attrValue = "of the Jungle"; $attrArray = array($attr1, $attr2); $attrList = new stdClass(); $attrList->attribute = $attrArray; $leadKey->leadAttributeList = $attrList; $leadRecord = new stdClass(); $leadRecord->leadRecord = $leadKey; $leadRecord->returnLead = false; $params = array("paramsSyncLead" => $leadRecord); $soapClient = new SoapClient($marketoSoapEndPoint ."?WSDL", $options); try { $result = $soapClient->__soapCall('syncLead', $params, $options, $authHdr); } catch(Exception $ex) { var_dump($ex); } if ($debug) { print "RAW request:\n" .$soapClient->__getLastRequest() ."\n"; print "RAW response:\n" .$soapClient->__getLastResponse() ."\n"; } print_r($result); ?> |
Sample Code – Java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 |
import com.marketo.mktows.*; import java.net.URL; import javax.xml.namespace.QName; import java.text.DateFormat; import java.text.SimpleDateFormat; import java.util.Date; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Hex; import javax.xml.bind.JAXBContext; import javax.xml.bind.JAXBElement; import javax.xml.bind.Marshaller; public class SyncLead { public static void main(String[] args) { System.out.println("Executing syncLead"); try { URL marketoSoapEndPoint = new URL("https://100-AEK-913.mktoapi.com/soap/mktows/2_1" + "?WSDL"); String marketoUserId = "demo17_1_809934544BFABAE58E5D27"; String marketoSecretKey = "27272727aa"; QName serviceName = new QName("http://www.marketo.com/mktows/", "MktMktowsApiService"); MktMktowsApiService service = new MktMktowsApiService(marketoSoapEndPoint, serviceName); MktowsPort port = service.getMktowsApiSoapPort(); // Create Signature DateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); String text = df.format(new Date()); String requestTimestamp = text.substring(0, 22) + ":" + text.substring(22); String encryptString = requestTimestamp + marketoUserId ; SecretKeySpec secretKey = new SecretKeySpec(marketoSecretKey.getBytes(), "HmacSHA1"); Mac mac = Mac.getInstance("HmacSHA1"); mac.init(secretKey); byte[] rawHmac = mac.doFinal(encryptString.getBytes()); char[] hexChars = Hex.encodeHex(rawHmac); String signature = new String(hexChars); // Set Authentication Header AuthenticationHeader header = new AuthenticationHeader(); header.setMktowsUserId(marketoUserId); header.setRequestTimestamp(requestTimestamp); header.setRequestSignature(signature); // Create Request ParamsSyncLead request = new ParamsSyncLead(); LeadRecord key = new LeadRecord(); ObjectFactory objectFactory = new ObjectFactory(); JAXBElement<String> email = objectFactory.createLeadRecordEmail("george@jungle.com"); key.setEmail(email); request.setLeadRecord(key); Attribute attr1 = new Attribute(); attr1.setAttrName("FirstName"); attr1.setAttrValue("George2"); Attribute attr2 = new Attribute(); attr2.setAttrName("LastName"); attr2.setAttrValue("of the Jungle"); ArrayOfAttribute aoa = new ArrayOfAttribute(); aoa.getAttributes().add(attr1); aoa.getAttributes().add(attr2); QName qname = new QName("http://www.marketo.com/mktows/", "leadAttributeList"); JAXBElement<ArrayOfAttribute> attrList = new JAXBElement(qname, ArrayOfAttribute.class, aoa); key.setLeadAttributeList(attrList); MktowsContextHeader headerContext = new MktowsContextHeader(); headerContext.setTargetWorkspace("default"); SuccessSyncLead result = port.syncLead(request, header, headerContext); JAXBContext context = JAXBContext.newInstance(SuccessSyncLead.class); Marshaller m = context.createMarshaller(); m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true); m.marshal(result, System.out); } catch(Exception e) { e.printStackTrace(); } } } |
Sample Code – Ruby
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
require 'savon' # Use version 2.0 Savon gem require 'date' mktowsUserId = "" # CHANGE ME marketoSecretKey = "" # CHANGE ME marketoSoapEndPoint = "" # CHANGE ME marketoNameSpace = "http://www.marketo.com/mktows/" #Create Signature Timestamp = DateTime.now requestTimestamp = Timestamp.to_s encryptString = requestTimestamp + mktowsUserId digest = OpenSSL::Digest.new('sha1') hashedsignature = OpenSSL::HMAC.hexdigest(digest, marketoSecretKey, encryptString) requestSignature = hashedsignature.to_s #Create SOAP Header headers = { 'ns1:AuthenticationHeader' => { "mktowsUserId" => mktowsUserId, "requestSignature" => requestSignature, "requestTimestamp" => requestTimestamp } } client = Savon.client(wsdl: 'http://app.marketo.com/soap/mktows/2_3?WSDL', soap_header: headers, endpoint: marketoSoapEndPoint, open_timeout: 90, read_timeout: 90, namespace_identifier: :ns1, env_namespace: 'SOAP-ENV') #Create Request request = { :lead_record => { :Email => "t@t.com", :lead_attribute_list => { :attribute => { :attr_name => "FirstName", :attr_value => "George" }, :attribute! => { :attr_name => "LastName", :attr_value => "of the Jungle" } } }, :return_lead => "false" } response = client.call(:sync_lead, message: request) puts response |