SOLVED

Marketo API Query "Merge"... Do I need to use {leadId}

Go to solution
kristalklug
Level 2

Marketo API Query "Merge"... Do I need to use {leadId}

Hi. 

Couple questions about REST API "merge".

 

  1. Do I need to use {leadId} or can I use some other API Name?
  2. What does the {leadId} refer to, is it Marketo's unique ID that it puts on a lead or the lead's email address?
  3. What is this doing, merging files where the {leadId} is the same or all the information on the leads' file is the same except for the {leadId} and so it merges the two files?
  4. Can I list out multiple API names in the brackets? For example, {leadId, facebookId, leadStatus}?
  5. Can I put a specific date or a range in this > 

    POST /rest/v1/leads/{leadId}/merge.json

  6. Can I do this in the web browser because I am prohibited to use Postman, Python, or any other software to run the CALL.

 

Thank you for your help.

4 ACCEPTED SOLUTIONS

Accepted Solutions
Darshil_Shah1
Level 10 - Community Advisor + Adobe Champion

Re: Marketo API Query "Merge"... Do I need to use {leadId}

  • Yes, you'd need to use the lead id, which is the unique identifier of person records in Marketo. This is the Id value of a lead, and it be pulled into the lead view (see snapshot below). You can very well just include this field in the view, and do a list export, you'd get it in the downloaded CSV file. Additionally, when you export leads using Query Lead/Bulk export, lead id is also included in the response.

Darshil_Shah1_0-1684338472499.png

  • When you open up a lead, its id is also part of the URL (see snapshot 2 below)

Darshil_Shah1_2-1684338657744.png

  • When you call this endpoint, the lead id in the path is the winning record (the one that'll persist post the merge action), and the id mentioned in the query parameter is the losing record (this will get merged, in case of conflicting values in field(s), the value in the winning record will take precedence, and will persist in the winning record post merge). You can specifiy more than one losing records' id values in the "leadids" query paramter in CSV format.
  • You can't specify multiple field names, you're only able to reference people for merging via their lead id. That's what you use for referencing the person records.
  • You can only specify the attributes listed in the API call definition - i.e., Winning record's id in the path, one or more losing lead Ids, mergeInCRM parameters as query string parameters. mergeInCRM is an optional paramter, and if set, it will attempt to merge the designated records in a natively-syced CRM.
  • I think using the URL bar will always result in a GET. To send POST requests from a browser, set up an HTML <form> with method="POST", use the action attribute for the REST-URL and input tags for other parameters. Though I never had to try this, as I usually use Postman/CLI for making requests. Do you really want to go via that route though? You might wanna get permissions before trying this via browser too.
  • Also, if both leads are in SFDC and one is a CRM lead and the other is a CRM contact, then the winner is the CRM contact (regardless which lead is specified as winner). If one of the leads is in SFDC and the other is Marketo only, then the winner is the SFDC lead (regardless of which lead is specified as winner).

Also, I'd recommend you to play around a bit using test records first, before trying this API call on your prod leads, you might not want to select wring lead as winning record in Marketo, as in case of conflicting values, the ones in the winning record always take precendence and is persisted. Hope this is helpful. Let us know if you have any questions.

 

View solution in original post

SanfordWhiteman
Level 10 - Community Moderator

Re: Marketo API Query "Merge"... Do I need to use {leadId}

1. Yes, you must use the ID. (It’s the only identifier that makes sense.)

 

2. The numeric Lead ID.

 

3a. I wouldn’t use the word “file” as we usually reserve that for downloadable assets. “Person record” would be more widely understood.

 

3b. Only one Marketo lead will have a given Lead ID. So no, it’s not merging records with the same Lead ID. It’s merging all records that have the losing Lead IDs into the one record that has the winning Lead ID. Much as you can do in the Marketo UI by selecting 2 people in the database.

 

4. No, I don’t think you quite understand what the API endpoint is doing. It’s merging entire records, where filled fields win over empty fields.

 

5. A date range doesn’t make sense in this context. What would it be filtering?

 

6. If you’re prohibited from using Postman, you should not be using this endpoint as it’s clear that your company doesn’t want you using the API, period.

View solution in original post

SanfordWhiteman
Level 10 - Community Moderator

Re: Marketo API Query "Merge"... Do I need to use {leadId}


I think using the URL bar will always result in a GET. To send POST requests from a browser, set up an HTML <form> with method="POST", use the action attribute for the REST-URL and input tags for other parameters.

That won’t work, because the REST API (correctly) won’t accept cross-origin requests. You’d have to launch your browser in relaxed CORS mode.

 

Like we both said, if you’re not allowed to use Postman, it doesn’t make sense that you can use a browser. Surely if IT says “no API use” they don’t want you working around that. (Though not clear how why you would have access to API credentials but not be allowed to use them.)

View solution in original post

Darshil_Shah1
Level 10 - Community Advisor + Adobe Champion

Re: Marketo API Query "Merge"... Do I need to use {leadId}

Thanks for confirming, Sandy! Appreciate it. Also, yes, if OP’s org doesn't allow using API platforms like Postman, then instead of thinking of workarounds for making API calls using browser, etc., they should get the permission the right way from their IT. 🙂

View solution in original post

4 REPLIES 4
Darshil_Shah1
Level 10 - Community Advisor + Adobe Champion

Re: Marketo API Query "Merge"... Do I need to use {leadId}

  • Yes, you'd need to use the lead id, which is the unique identifier of person records in Marketo. This is the Id value of a lead, and it be pulled into the lead view (see snapshot below). You can very well just include this field in the view, and do a list export, you'd get it in the downloaded CSV file. Additionally, when you export leads using Query Lead/Bulk export, lead id is also included in the response.

Darshil_Shah1_0-1684338472499.png

  • When you open up a lead, its id is also part of the URL (see snapshot 2 below)

Darshil_Shah1_2-1684338657744.png

  • When you call this endpoint, the lead id in the path is the winning record (the one that'll persist post the merge action), and the id mentioned in the query parameter is the losing record (this will get merged, in case of conflicting values in field(s), the value in the winning record will take precedence, and will persist in the winning record post merge). You can specifiy more than one losing records' id values in the "leadids" query paramter in CSV format.
  • You can't specify multiple field names, you're only able to reference people for merging via their lead id. That's what you use for referencing the person records.
  • You can only specify the attributes listed in the API call definition - i.e., Winning record's id in the path, one or more losing lead Ids, mergeInCRM parameters as query string parameters. mergeInCRM is an optional paramter, and if set, it will attempt to merge the designated records in a natively-syced CRM.
  • I think using the URL bar will always result in a GET. To send POST requests from a browser, set up an HTML <form> with method="POST", use the action attribute for the REST-URL and input tags for other parameters. Though I never had to try this, as I usually use Postman/CLI for making requests. Do you really want to go via that route though? You might wanna get permissions before trying this via browser too.
  • Also, if both leads are in SFDC and one is a CRM lead and the other is a CRM contact, then the winner is the CRM contact (regardless which lead is specified as winner). If one of the leads is in SFDC and the other is Marketo only, then the winner is the SFDC lead (regardless of which lead is specified as winner).

Also, I'd recommend you to play around a bit using test records first, before trying this API call on your prod leads, you might not want to select wring lead as winning record in Marketo, as in case of conflicting values, the ones in the winning record always take precendence and is persisted. Hope this is helpful. Let us know if you have any questions.

 

SanfordWhiteman
Level 10 - Community Moderator

Re: Marketo API Query "Merge"... Do I need to use {leadId}


I think using the URL bar will always result in a GET. To send POST requests from a browser, set up an HTML <form> with method="POST", use the action attribute for the REST-URL and input tags for other parameters.

That won’t work, because the REST API (correctly) won’t accept cross-origin requests. You’d have to launch your browser in relaxed CORS mode.

 

Like we both said, if you’re not allowed to use Postman, it doesn’t make sense that you can use a browser. Surely if IT says “no API use” they don’t want you working around that. (Though not clear how why you would have access to API credentials but not be allowed to use them.)

Darshil_Shah1
Level 10 - Community Advisor + Adobe Champion

Re: Marketo API Query "Merge"... Do I need to use {leadId}

Thanks for confirming, Sandy! Appreciate it. Also, yes, if OP’s org doesn't allow using API platforms like Postman, then instead of thinking of workarounds for making API calls using browser, etc., they should get the permission the right way from their IT. 🙂

SanfordWhiteman
Level 10 - Community Moderator

Re: Marketo API Query "Merge"... Do I need to use {leadId}

1. Yes, you must use the ID. (It’s the only identifier that makes sense.)

 

2. The numeric Lead ID.

 

3a. I wouldn’t use the word “file” as we usually reserve that for downloadable assets. “Person record” would be more widely understood.

 

3b. Only one Marketo lead will have a given Lead ID. So no, it’s not merging records with the same Lead ID. It’s merging all records that have the losing Lead IDs into the one record that has the winning Lead ID. Much as you can do in the Marketo UI by selecting 2 people in the database.

 

4. No, I don’t think you quite understand what the API endpoint is doing. It’s merging entire records, where filled fields win over empty fields.

 

5. A date range doesn’t make sense in this context. What would it be filtering?

 

6. If you’re prohibited from using Postman, you should not be using this endpoint as it’s clear that your company doesn’t want you using the API, period.