Update Leads in Bulk v2
This downloads our complete API collection, including all endpoints—not just this specific endpoint.
Lets you update multiple fields for multiple leads. You can update a maximum of 25 leads.
- Leads will be updated based on the SearchByKey.
- If SearchByKey is not passed, the API will update leads based on the ProspectId you pass for each lead in the LeadPropertiesList array.
- If you don’t pass the ProspectId for a particular lead, that lead won’t be updated.
- Under the Options node (Optional), you can pass PushNonExistentLeadsToUnProcessedList parameter.
- If True, leads which don’t exist in the system will appear in UnProcessedLeads in the response. E.g. –
{ "Status": { "TotalCount": 1, "SuccessCount": 0, "FailureCount": 0, "UnProcessedCount": 1, "Message": "Error" }, "Details": { "UnProcessedLeads": [ { "Identifier": "EmailAddress", "IdentifierValue": "johnwick @gmail.com", "Reason": "Lead does not exist in the system or You do not have permission to update the lead" } ] } } - If False, or if the Options node isn’t passed, leads which don’t exist in the system will appear in FailedLeads in the response. E.g. –
{ "Status": { "TotalCount": 1, "SuccessCount": 0, "FailureCount": 1, "Message": "Error" }, "Details": { "FailedLeads": [ { "Identifier": "EmailAddress", "IdentifierValue": "johnwick@gmail.com", "Reason": "Lead does not exist in the system or You do not have permission to update the lead" } ] } }
- If True, leads which don’t exist in the system will appear in UnProcessedLeads in the response. E.g. –
Note: Lead update permissions (see Sales Groups) and permissions set on lead fields (see Permission Templates) will apply. Users without sufficient permissions, won’t be able to update corresponding leads and/or lead fields.
FAQ
Why am I getting the error “Lead does not exist in the system or You do not have permission to update the lead” when using the Update Leads in Bulk v2 API?
This error occurs if your account requires a mandatory country code for the phone field, but the phone number in your request is missing it. The API validates the phone field based on this setting, so if the country code is not included, it fails to recognize the lead. To fix this, ensure that the phone number includes the country code in the request.
Example:
By including the country code (+91- in this example), the API will correctly validate and update the lead.
{
"SearchByKey": "Phone",
"Options": {
"PushNonExistentLeadsToUnProcessedList": true
},
"LeadPropertiesList": [
{
"Fields": [
{
"Attribute": "Phone",
"Value": "+91-1234554321"
},
{
"Attribute": "FirstName",
"Value": "Sam"
}
]
}
]
}
API URL
URL
POST
https://{host}/v2/LeadManagement.svc/Lead/Bulk/UpdateV2?accessKey=AccessKey&secretKey=SecretKey
Request
Content-Type: application/jsonJSON Body/Payload
{
"SearchByKey": "EmailAddress",
"Options": {
"PushNonExistentLeadsToUnProcessedList": false
},
"LeadPropertiesList": [
{
"Fields": [
{
"Attribute": "EmailAddress",
"Value": "johnwick@gmail.com"
},
{
"Attribute": "mx_FirstName",
"Value": "John"
},
{
"Attribute": "mx_LastName",
"Value": "Wick"
},
{
"Attribute": "Age",
"Value": "33"
}
]
},
{
"Fields": [
{
"Attribute": "EmailAddress",
"Value": "jack@gmail.com"
},
{
"Attribute": "mx_FirstName",
"Value": "Jack"
},
{
"Attribute": "mx_LastName",
"Value": "Sparrow"
},
{
"Attribute": "PhoneNumber",
"Value": "9876543210"
}
]
}
]
}
Request Parameters
| Parameter | Description |
|---|---|
| SearchByKey | Leads will be updated based on the lead attribute passed here. You must pass a unique field. |
| Options | This is optional. You can pass PushNonExistentLeadsToUnProcessedList parameter as True or False. |
| LeadPropertiesList | Pass Attribute Value pairs for the lead fields and values you want to update. Note: You must pass the schema names of the lead fields. |
Response
200 OK
Content-Type: application/json
{
"Status": {
"TotalCount": 2,
"SuccessCount": 2,
"FailureCount": 0,
"Message": "Processed"
},
"Details": {
"SuccessfulLeads": [
{
"Identifier": "EmailAddress",
"IdentifierValue": "james@gmail.com"
},
{
"Identifier": "EmailAddress",
"IdentifierValue": "jack@gmail.com"
}
]
}
}
HTTP Response Codes
| Code | Description |
|---|---|
| 200 OK | This is the status code for successful API call. |
| 401 Unauthorized | The API call was made with invalid access credentials. Check your AccessKey and SecretKey. |
| 400 Bad Request | The message body on the request is not as per API specification. Make sure that content type is set to “application/json” and the JSON body has correct attribute names and structure. |
| 404 Not Found | The API could not be found. Please check the API signature. |
| 429 Too Many Requests | API calls exceeded the limit of 25 in 5 second(s) |
| 500 Internal Server Error | The API called failed. There could be many reasons for it. Check the exception message to get more details. |
