loading..
< View all articles in API & Webhooks.

Lead Management API in LeadSquared

Lead Meta-data

This API will return the list of all Lead fields in the form of JSON array. It will help you learn the schema of LeadSquared. For example, when you create a lead, you need to know the internal schema name of a field such as First Name, or of a custom field you have created.

GET  https://api.leadsquared.com/v2/LeadManagement.svc/LeadsMetaData.Get?accessKey=<accessKey>&secretKey=<secretKey>

The output will be an array of details of each lead. Example:

[
..
{"SchemaName":"mx_Webinar_Notes","DisplayName":"Webinar Comments","DataType":"Text","IsMandatory":false},
..
]

 

SchemaName is the internal name of the field that you will use in all your Lead API calls.  Display Name is the name of the field that you will see in LeadSquared user interface. DataType can be text, datetime, number or Select.  If it is Select, then you will also get the “Options” of the Select field in an additional parameter as an array of strings.

Create a Lead

This API will help you create a lead in LeadSquared.  You will need to supply at least one of FirstName, LastName or EmailAddress to create a lead. We recommend you always supply EmailAddress, since that uniquely identifies leads in LeadSquared.

POST https://api.leadsquared.com/v2/LeadManagement.svc/Lead.Create?accessKey=<accessKey>&secretKey=<secretKey>

Post lead details in JSON format in the body of the message

[
    {
        "Attribute": "EmailAddress",
        "Value": "john.smith@acmeconsulting.co"
    },
    {
        "Attribute": "FirstName",
        "Value": " John"
    },
    {
        "Attribute": "LastName",
        "Value": " Smith"
    }
]

This API will respond with the Lead ID of the lead created.

Convert a tracked visitor to Lead

This API is useful when you want to convert a tracked website visitor to Lead.

If your LeadSquared account supports tracking of visits by unknown visitors (please check your LeadSquared account manager if you are not sure about it), then LeadSquared tracks each unique visitor using a tracking Id.  Using this Id, LeadSquared knows the lead source, visitor’s website behavior, 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 Chrome broswer as shown below. If you see a unique value after you type MXCProspectId , it means that unknown viistors are being tracked.

MXCProspectId

You should get MXCProspectId on your webpage using custom JavaScript code. Note that since the value of  MXCProspectId  comes from a cookie, there may be some delay in getting it.  Put an artificial delay of 2 seconds before reading it or fetch the value after form submssion (because most of cookies data would be available by the time form submission happens).

Use the Lead.Convert API with signature as follows to capture the converted lead.

POST https://api.leadsquared.com/v2/LeadManagement.svc/Lead.Convert?accessKey=<accesskey>&secretKey=<secreteKey>&leadId=<value of MXCProspectId>&postUpdatedLead=true

Keep value of “postUpdatedLead” as “true”.

Post lead details in JSON format in the body of the message. An example:

[
    {
        "Attribute": "Company",
        "Value": "MarketXpander Services"
    },
    {
        "Attribute": "OwnerId",
        "Value": "ID of the user who will own this record"
    }
]

Update a Lead

This API will help you update a lead record with new details.  The details supplied here will overwrite the corresponding fields in the database.

POST https://api.leadsquared.com/v2/LeadManagement.svc/Lead.Update?accessKey=<accesskey>&secretKey=<secreteKey>&leadId=<the lead ID you want to edit>

Post lead details in JSON format in the body of the message. An example:

[
    {
        "Attribute": "Company",
        "Value": "MarketXpander Services"
    },
    {
        "Attribute": "OwnerId",
        "Value": "ID of the user who will own this record"
    }
]

Create Or Update

A very practically useful API, that will update the lead if it exists, else will create a new one. The API will match either email address or phone number to check the existence of the lead in the system. While matching for the phone number, if there are two leads matching the number provided, then it will update the first matched lead.

POST https://api.leadsquared.com/v2/LeadManagement.svc/Lead.CreateOrUpdate?postUpdatedLead=false&accessKey=<accesskey>&secretKey=<secretKey>

You can POST the details of the lead in JSON format in the message body.

Option 1 – Match phone number. Notice the “SearchBy” parameter.

Option 2 – Match email address.

[
    {
        "Attribute": "EmailAddress",
        "Value": "john.smith@acmeconsulting.co"
    },
    {
        "Attribute": "FirstName",
        "Value": "John"
    },
    {
        "Attribute": "LastName",
        "Value": "Smith"
    },
    {
        "Attribute": "Phone",
        "Value": "+919845098450"
    },
    {
        "Attribute": "SearchBy",
        "Value": "Phone"
    }
]

 

Finding Leads

Get list of Leads emulating “quick search”

GET  https://api.leadsquared.com/v2/LeadManagement.svc/Leads.GetByQuickSearch? accessKey=<accessKey>&secretKey=<secretKey>&key=<quick search phrase>

The quick search by default works on lead name, email address and company name. You can configure of which fields will be searched in respective settings of fields in Settings -> Custom Fields section.

Get a Lead by its email address

GET https://api.leadsquared.com/v2/LeadManagement.svc/Leads.GetByEmailaddress? accessKey=<accessKey>&secretKey=<secretKey>&emailaddress=<correct lead email address>

Get a lead by its ID

GET https://api.leadsquared.com/v2/LeadManagement.svc/Leads.GetById? accessKey=<accessKey>&secretKey=<secretKey>&id=<lead id – GUID>

Search Leads by specific Lead criteria

POST https://api.leadsquared.com/v2/LeadManagement.svc/Leads.Get? accessKey=<accessKey>&secretKey=<secretKey>


Post the query details in JSON format in the body of the request message. 

{
    "Parameter": {
        "LookupName": "FieldName",
        "LookupValue": "Value you want to search for",
        "SqlOperator":" >, <=, =, LIKE, etc"
    },
    "Columns": {
        "Include_CSV": "ProspectID, FirstName, LastName, EmailAddress"
    },
    "Sorting": {
        "ColumnName": "CreatedOn",
        "Direction": "1"
    },
    "Paging": {
        "PageIndex": 1,
        "PageSize": 100
    }
}

The API will return array of leads. The SqlOperator emulates an SQL operator in the where clause.  To configure the search, list the fields you want to see in the search results in “Columns” parameter.  “Sorting” will set the sort order and “Paging” will be useful when you are dealing with large number of records. PageIndex is which page you would like to retrieve data from, and it is related to PageSize. For example: You may want to retrieve 50 records at a time, so you would retrieve the first set by passing PageSize=50 and PageIndex=1, and second 50 records by passing PageSize=50 and PageIndex=2, and so on.

Send Email to a Lead through API

This API allows you to send an email to a lead. The content & subject for the email is picked from Content Library. You just have to pass the name of the email content item in the library.

POST https://api.leadsquared.com/v2/EmailMarketing.svc/SendMail?accessKey={accessKey}&secretKey={secretKey}

Data to POST:

{
    "leadId": "",
    "EmailContentName": ""
}

It will return the following when successful:

{
“Status”: “Success”
}

Get pending tasks of a Lead

Get a list of pending tasks of a given lead

GET  https://api.leadsquared.com/v2/LeadManagement.svc/RetrieveTaskByLeadId? accessKey=<accessKey>&secretKey=<secretKey>&leadId=<Lead-ID>

This will return an array of Tasks with all the details for the lead.