Update Leads in Bulk v2

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"
            }
          ]
        }
      }

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.

 

API URL

POST
https://{host}/v2/LeadManagement.svc/Lead/Bulk/UpdateV2?accessKey=AccessKey&secretKey=SecretKey
Copy URL

Request

JSON Body/Payload

Content-Type: application/json

{
  "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"
        }
      ]
    }
  ]
}

JSON Properties

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 Code

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.