Capture Leads

This is a generic API to capture leads from your lead sources. The API creates or updates leads based on the data provided in the JSON body.

This API essentially combines the power of four APIs – Lead.Create, Lead.Update, Lead.Convert, Lead.CreateOrUpdate. It saves you from writing any code to handle duplicates records.

How it Works

  • If you don’t pass any of ProspectId, EmailAddress, Phone then a new Lead is created.
  • If you pass one or more of ProspectId, EmailAddress, Phone then we try to find a matching lead first based on ProspectId, then on EmailAddress and then on Phone. ProspectId will be given priority over EmailAddress when both of them are passed.
  • If ProspectId matches with an anonymous visitor (which is not yet converted to Lead) then a new Lead is created (leadid is the same as the ProspectId in this case). Refer the note below on Note on Anonymous Visitor Tracking.
  • If ProspectId matches with an existing Lead and the EmailAddress provided does not match, then a new lead is created.
  • If ProspectId matches with an existing Lead and the EmailAddress is not provided,  lead is updated.
  • If ProspectId and Email both match with an existing Lead,  the lead is updated.
  • If ProspectId does not match but EmailAddress matches, the lead is updated.
  • If No match is found with ProspectId, Email or Phone then new Lead is created.
  • If you are passing the same Lead Details for the second time, then the Lead Source is not updated
  • If you specify “SearchBy” attribute in the JSON body, then the priority will be given to “SearchBy” attribute.[Using “SearchBy”  you can match by phone number or email address.]
  • If you pass all of this ProspectId, EmailAddress, Phone and SearchBy attribute then SearchBy will be ignored.

SearchBy attribute search if any lead exists with the provided value. If exist it will update the lead

Note: Source related fields will be captured in repeated Capture Lead calls.

In all successful (where lead is created or updated) scenarios, a Lead Capture activity is posted to the Lead so you get to see the log of creation and resubmissions events.

Note on Anonymous Visitor Tracking

LeadSquared tracks each unique web visitor – even who have not converted to lead – using a tracking Id.  Using this Id, LeadSquared knows the lead source, visitor’s website behaviour, location etc. This tracking Id is available using a JavaScript variable called MXCProspectId.  You can verify if your visitors are being tracked by looking for MXCProspectId variable in Console of your browser as shown below. If you see a unique value after you type MXCProspectId , it means that unknown visitors are being tracked.

MXCProspectId

You should get MXCProspectId on your webpage using custom JavaScript code.  This MXCProspectId should be passed as ProspectId in the JSON body of Lead.Capture API if you intend to convert an existing visitor to a Lead.

API URL

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

Request

JSON Body/Payload

Content-Type: application/json

[
  {
  "Attribute":"FirstName",
  "Value":"Bret"
  },
  {
  "Attribute":"LastName",
  "Value":"Lee"
  },
  {
  "Attribute":"EmailAddress",
  "Value":"bret.lee@australia.com"
  },
  {
  "Attribute":"Phone",
  "Value":"8888888888"
  },
  {
  "Attribute":"ProspectID",
  "Value":"xxxxxxxx-d168-xxxx-9f8b-xxxx97xxxxxx"
  },
  {
  "Attribute":"SearchBy",
  "Value":"Phone"
  }
]

JSON Properties

Parameter Description
Attribute

Schema name of the Lead field. To get Schema name for all Lead fields use LeadsMetaData API.

Value

Value to the given attribute

Response

200 OK

Content-Type: application/json

{
  "Status": "Success",
  "Message": {
    "Id": "08ed843e-2919-42f7-ae88-46904d2f4d90",
    "RelatedId": "6405359a-f568-4159-9d81-3b76c0a73087"
  }
}

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.