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.
The lead capture API 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.
Note: To ensure more reliable lead capture, see Async API. Async API ensures zero leakage and peak usage protection.
| Query String Parameter | Description | Values |
| LeadUpdateBehavior (Optional) | Pass this parameter in the query string to define the lead update behavior.
For example, https://{{Host}}/v2/LeadManagement.svc/Lead.Capture?accesskey={{Admin_AccessKey}}&secretkey={{Admin_SecretKey}}&LeadUpdateBehavior=DoNotUpdate |
DoNotUpdate |
| UpdateOnlyEmptyFields | ||
| DoNotUpdateUniqueFields |
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.
* The lead capture activity is also captured in case the duplicate lead exception is thrown by the API. The lead capture event, in this case, will be posted on the existing lead against which the duplicate lead creation request is being attempted.
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.
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.
Note: To associate a lead with an Account, pass the Attribute
RelatedCompanyId. To obtain this Id, refer to Get an Account. This is optional.API URL
URL
POST
https://{host}/v2/LeadManagement.svc/Lead.Capture?accessKey=AccessKey&secretKey=SecretKey
Request
Content-Type: application/jsonJSON Body/Payload
[
{
"Attribute":"FirstName",
"Value":"Wim"
},
{
"Attribute":"LastName",
"Value":"Wenders"
},
{
"Attribute":"EmailAddress",
"Value":"wim.wenders@example.com"
},
{
"Attribute":"Phone",
"Value":"7777777777"
},
{
"Attribute":"ProspectID",
"Value":"45b5fded-e696-45a6-9fbb-c6af6178229e"
},
{
"Attribute":"SearchBy",
"Value":"Phone"
},
{
"Attribute":"RelatedCompanyId",
"Value":"82a19544-ef4f-4cef-a09c-d68b939742f9"
}
]
Request Parameters
| Parameter | Description |
|---|---|
| Attribute | Schema name of the Lead field. To get Schema name for all Lead fields use LeadsMetaData API. |
| Value | Value assigned to the given attribute. |
Response
200 OK
Content-Type: application/json
{
"Status": "Success",
"Message": {
"Id": "13aa67f8-c2ac-437c-9eb5-e5b1934fbfcc",
"RelatedId": "330fba67-6795-46c2-9dad-077794077f70",
"IsCreated": true
}
}
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. |
