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.
Note: To ensure more reliable lead capture, see Async API. Async API ensures zero leakage and peak usage protection.
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
Schema name of the Lead field. To get Schema name for all Lead fields use LeadsMetaData API.
Value assigned to the given attribute.
HTTP Response Codes
This is the status code for successful API call.
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.