Search leads via REST API

This feature allows you to search a campaign for an existing lead based using a phone or email field via our REST API.

A nice example of this would be checking if you have a particular number or email in a campaign BEFORE submitting the lead and having it rejected as a duplicate.

Getting Started

In order to search via the REST API, you'll need a REST API key with the correct permissions.

Head to the Admin tab > Tech Hub > REST API to get started:

1) Create yourself an Administrator Key

2) Ensure the Administrator Key has the Leads > Search permission

3) Activate your Administrator Key

You'll also need to know your campaign ID, find this by editing your campaign and checking the URL:

Performing the Search

We allow you to search using the email OR the phone fields, you'll just need to amend the relevant "search" field.

You'll be sending a JSON Post to the below URL:

https://{account}.leadbyte.com/restapi/v1.3/leads/search

With the following body:

{
"key": "[API KEY GOES HERE]",
"searches": [
{
"campaignId": [CAMPAIGN ID GOES HERE],
"email": "[EMAIL TO SEARCH FOR GOES HERE]"
}
]
}

Response

If the email IS found in the campaign, you'll receive a response similar to that shown below:

{
    "status": "Success",
    "message": "",
    "warnings": [],
    "totalMatches": 1,
    "searches": [
        {
            "campaignId": 565,
            "email": "example@email.com",
            "results": [
                {
                    "c1": "",
                    "c2": "",
                    "c3": "",
                    "sub_supplier_id": "0",
                    "title": "",
                    "firstname": "",
                    "lastname": "",
                    "email": "example@email.com",
                    "phone1": "0650111111",
                    "phone2": "",
                    "phone3": "",
                    "queue_ref": null,
                    "leadId": 499791,
                    "campaignId": 565,
                    "received": "2022-03-15T10:30:46Z"
                }
            ],
            "matches": 1
        }
    ]
}

If the email is NOT found in the campaign, you'll receive a response similar to that shown below:

{
    "status": "Success",
    "message": "",
    "warnings": [],
    "totalMatches": 0,
    "searches": [
        {
            "campaignId": 565,
            "email": "example@email.com",
            "results": [],
            "matches": 0
        }
    ]
}

Adding additional lead info to your search results

When returning search results, we provide you with a few important lead fields.

However, if you require other lead fields to be returned with your results then you'd need to amend your request accordingly:

{
"key": "[API KEY GOES HERE]",
"searches": [
{
"campaignId": [CAMPAIGN ID GOES HERE],
"email": "[EMAIL TO SEARCH FOR GOES HERE]",
"extrafields": [
"fieldname1","fieldname2","fieldname3"
]
}
]
}

Which would amend your results like this:

{
"status": "Success",
"message": "",
"warnings": [],
"totalMatches": 1,
"searches": [
{
"campaignId": 565,
"email": "example@email.com",
"extrafields": [
"street1",
"postcode"
],
"results": [
{
"c1": "",
"c2": "",
"c3": "",
"sub_supplier_id": "0",
"title": "",
"firstname": "",
"lastname": "",
"email": "example@email.com",
"phone1": "0650111111",
"phone2": "",
"phone3": "",
"fieldname1": "ABC",
"fieldname2": "",
"fieldname3": "123",
"queue_ref": null,
"leadId": 499792,
"campaignId": 565,
"received": "2022-03-15T10:30:46Z"
}
],
"matches": 1
}
]
}

LeadByte Support

Comments