Introduction

Welcome to Lusha API documentation. Our REST API allows you to query our vast dataset of business profiles and companies and receive and get an enriched profile of the item you were looking for. Our two main calls are:
Company API, which returns company data based on domain or company name
Person API, which returns contact data for a business profile

As noted before, our API’s are RESTful, and all requests should be made over SSL. The response bodies are encoded in JSON.

Please note that we operate as a search platform, and therefore the information we retrieve is not created or interfered directly by us, rather than retrieved from the web or from contribution of relevant data from our trusted business partners. To learn more about our dataset of business profiles and on the ways we collect and use such business profiles, please read our Privacy Policy.

Note: A credit will be deducted for each successful match. A match is a request that yielded results.

Lusha API endpoint
https://api.lusha.com/

Authentication

Requests are authenticated by your API key.
When making a call, you’ll have to specify this API key with the Authorization header. Here’s an example:

Note that your API key is what identifies you and your usage, so please don’t share it with anyone outside of your organization.

$ curl "https://api.lusha.com/person?firstName=Rob&lastName=Taylor&company=intercom" -H "api_key:YOUR_API_KEY"

Errors

Lusha uses common HTTP response codes to indicate the status of the API request.
In case of an error, Lusha API will return the correspondent code.

HTTP Status codes
200 OK – Successful request

400 Bad request – Badly formatted request

401 Unauthorized – The API key is invalid

403 Unauthorized – Your account is not active. Please contact support

404 Not found – The requested endpoint was not found

412 - The request failed due to invalid syntax that was provided. Please make sure to send a full name field that contains a valid first & last name.

429 Limit reached – You’ve reached your trial limit, please contact support for upgrade

451 - We are unable to process this contact request due to our GDPR regulations.

499 - Request failed due to request timeout.

5XX Server error – There’s a problem on Lusha’s end

Rate limiting

You can make 50 requests per second to each API.

Check the returned HTTP headers to see your current rate limit state.

Header
Description
RateLimit-Limit
The number of total allowed requests per second.
RateLimit-Remaining
The number of remaining requests in current rate limit window.
RateLimit-Reset
The time remaining in seconds until the quota is reset.

Example of request response:
1
2
3
4
5
6
HTTP/1.1 200 OK
Date: Mon, 05 Feb 2018 17:40:00 GMT
Status: 200 OK
RateLimit-Limit: 50
RateLimit-Remaining: 45
RateLimit-Reset: 1
Example rate limit error response.
1
2
3
4
5
6
7
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1

Content-Type: application/json
{ "message": "API rate limit exceeded" }

Person Bulk API

Bulk API enables you to get even more details with fewer API calls. Receive job title, seniority, and department in your API requests. Additionally, now API users can send only ONE request to retrieve a maximum of 100 objects from Lusha (a credit will be deducted for each successful match). This helps you reduce the daily API usage for any integration between Lusha API and to 3rd party.

Endpoint URL:

POST https://api.lusha.com/bulk/person -H api_key:API_KEY

Person request schema:

{
 "contacts":[
  {
   "contactId": (required, unique, type string)
   "firstName": (required, type string),
   "lastName": (required, type string),
   "location": (optional, type string),
   "linkedinUrl": (optional, type string), 
   "companies": (required) [
    {
     "name": (required , type string, min_length=2),
     "domain": (optional, type string, min_length=4),
     "isCurrent":  (required, type bool),
     "jobTitle": (optional, type string, min_length=2)
     "fqdn": (optional, type string)
     "companySocialId": (optional, type string)
    }
   ]
  }
 ],
 "filters":{
   "property": (optional, one of ("emailAddresses", "phoneNumbers"))
 },
}

Request body length: max 100 objects.

HTTP parameters

contacts

Required

Contact []
array of contact
filters

Optional

Object

For cases when you want to get a hit only in
case a phone number for the person exists, you should add the following to the request:

{ filters: property: “phoneNumbers” } }

Alternatively, when you require an email for your results, you should add this:

{ filters: property: “emailAddresses” } }

By default, Lusha returns result for every record that has at least one of them.

 

Contact parameters
contactId

Required

String
Your contact id identifier to find the contact in the response.
firstName

Required

String
First name of the person (e.g – Dustin)
lastName

Required

String
Last name of the person (e.g – Moskovitz)
location

Optional

String
Raw location of the person – can be country / city / raw location (e.g – Singapore / Chicago)
linkedinUrl

Optional

String
The LinkedIn url of the person
companies

Required

ContactCompany []
Company

 

Contact Company
name

Required

String
The name of the company (e.g – Lusha)
domain

Optional

String
The domain name (e.g – lusha.com)
isCurrent

Required

Boolean
Last company of the person (e.g – true)
jobTitle

Optional

String
The contact jobTitle at the current company
fqdn

Optional

String
The fqdn name (e.g – lusha.com)
companySocialId

Optional

String
The social id if the company

Person/Company Bulk API
Person response schema:
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
{
  "contacts": {
    "1": {
      "companyId": "11",
      "firstName": "firstName",
      "lastName": "lastName",
      "fullName": "firstName lastName",
      "emails": ["example@lusha.com"],
      "phones": ["+1 256-318-1196"],
      "location": {
        "country": "United Kingdom",
        "countryIso2": "GB",
        "continent": "Europe"
      },
      "jobTitle": {
        "title": "Director of Studies for Computer Science",
        "seniority": "Director",
        "departments": [
          "Engineering & Technical",
          "Operations"
        ]
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/name"
      }
    },
    "2": {
      "companyId": "12",
      "firstName": "firstName2",
      "lastName": "lastName2",
      "fullName": "firstName2 lastName2",
      "emails": ["example2@lusha.com"],
      "phones": ["+1 256-318-1196"],
      "location": {
        "country": "United Kingdom",
        "countryIso2": "GB",
        "continent": "Europe"
      },
      "jobTitle": {
        "title": "Director of Studies for Computer Science",
        "seniority": "Director",
        "departments": [
          "Engineering & Technical",
          "Operations"
        ]
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/name2"
      }
    }
  },
  "companies": {
    "11": {
      "name": "company name",
      "company_size": [
        {
          "min": "50",
          "max": "100"
        }
      ],
      "revenue_range": [
        {
          "min": "1000000000",
          "max": null,
          "string": "$1,000,000,000+"
        }
      ],
      "revenue": "$1,000,000,000+",
      "founded": "2002",
      "description": "company description",
      "domains": {
        "homepage": "companyDomain.com"
      },
      "industry_tags": [
        "Electronics",
        "Consumer Electronics"
      ],
      "industry_primary_group": "Consumer Electronics",
      "location": {
        "city": "Cupertino",
        "country": "United States",
        "state": "California"
      },
      "social": {
        "linkedin": "https://www.linkedin.com/company/name",
        "twitter": "https://twitter.com/name"
      }
    },
    "12": {
      "name": "company name2",
      "company_size": [
        {
          "min": "50",
          "max": "100"
        }
      ],
      "revenue_range": [
        {
          "min": "1000000000",
          "max": null,
          "string": "$1,000,000,000+"
        }
      ],
      "revenue": "$1,000,000,000+",
      "founded": "2002",
      "description": "company description",
      "domains": {
        "homepage": "companyDomain2.com"
      },
      "industry_tags": [
        "Electronics",
        "Consumer Electronics"
      ],
      "industry_primary_group": "Consumer Electronics",
      "location": {
        "city": "Cupertino",
        "country": "United States",
        "state": "California"
      },
      "social": {
        "linkedin": "https://www.linkedin.com/company/name2",
        "twitter": "https://twitter.com/name2"
      }
    }
  }
}

Company Bulk API

The company API provides information about any organization you look for to help you get a complete picture, such as overview, social network presence, and location (a credit will be deducted for each successful match).

Endpoint URL:

POST https://api.lusha.com/bulk/company -H api_key:API_KEY

Company request schema:

{
  "companies": [
    {
      "id": (required, unique, type string),
      //need at least one field from the following:
      "fqdn": (optional, type string),
      "domain": (optional, type string),
      "name": (optional, type string)
    }
  ]
}

Company request body length: max 100 objects.

HTTP parameters

companies

Required

Company []
array of Company to search for

 

Company parameters
Id

Required

String
Your company identifier to find the company in the response.
name

Required if domain/fqdn is not provided

String
The name of the company (e.g – Lusha)
domain

Required if name/fqdn is not provided

String
The domain name (e.g – Lusha.com)
fqdn

Required if name/domain is not provided

String
The fqdn name (e.g – Lusha.com)

Company response schema:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "11": {
    "name": "company name",
    "companySize": [
      {
        "min": "50",
        "max": "100"
      }
    ],
    "revenueRange": [
      {
        "min": "1000000000",
        "max": null,
        "string": "$1,000,000,000+"
      }
    ],
    "revenue": "$1,000,000,000+",
    "founded": "2002",
    "description": "company description",
    "domains": {
      "homepage": "companyDomain.com"
    },
    "industryTags": [
      "Electronics",
      "Consumer Electronics"
    ],
    "industryPrimaryGroup": "Consumer Electronics",
    "location": {
      "city": "Cupertino",
      "country": "United States",
      "region": null,
      "state": "California",
      "street": null
    },
    "social": {
      "linkedin": "https://www.linkedin.com/company/name",
      "twitter": "https://twitter.com/name"
    }
  }
}

Person API

The person API lets you look up a person data based on his name and the company,
or the domain of the company he works for. For example, you can get the person’s
location, email and phone number, as well as his or her social network username.

HTTP request

GET https://api.lusha.com/person?firstName=:firstName&lastName=:lastName&company=:company

(Where :firstName is the first name of the person you’re looking for, and
:lastName is his last name. :company is the name of the company) You can opt to
get results only in case a phone number or email exist. To do that, add an
optional parameter named property. For cases when you want to get a hit only in
case a phone number for the person exists, you should add property=phoneNumbers
to your request. Alternatively, when you require an email for your results, you
should add property=emailAddresses. By default, Lusha returns result for every
record that has at least one of them. So, if, for example, you want to get only
records with phone numbers, this is the way to go:

GET https://api.lusha.com/person?firstName=:firstName&lastName=:lastName&company=:company&property=phoneNumbers

In order to search by more than one company, you can use a POST request with payload as described below.

POST https://api.lusha.com/person

{
    “firstName”: :firstName,
    “lastName”: :lastName,
    “organizations”: [
        {
            “company”: :company1,
            “domain”: :domain1,
            “isCurrent“: true
        },
        {
            “company”: :company2,
            “domain”: :domain2,
            “isCurrent“: false
        }
    ]
}

For each request, Lusha returns your current usage status under the “meta” tag

HTTP parameters

firstName

Required

First name of the person (e.g – Dustin)
lastName

Required

Last name of the person (e.g – Moskovitz)
company

Required if domain is not provided

The name of the company (e.g – Facebook)
domain

Required if company is not provided

The domain name (e.g – facebook.com)
linkedinUrl

Optional

The LinkedIn url of the person

Person Attributes
Name

  • fullName – Full name of the person.
  • firstName – First name of the person.
  • familyName – Last name of the person.

Location

  • raw_location – Full representation of the location (optional).
  • state – Full text of the person’s state (optional).
  • stateCode – Two digit code of the person’s state (optional).
  • country – The country where the person lives.
  • country_iso2 – Two-digit code of the person’s country.
  • continent – Full text of the person’s continent.
  • is_eu_contact – true/false.

Email Address

  • email – The email address of the person.
  • type – Type of address. Might be work,
    personal or other.
  • mailServer – The mail server of the email we found.

Phone Number

  • internationalNumber – The international representation of the phone number.
  • localizedNumber – The localized phone number.
  • countryCode – Country code of the
    phone number.
  • regionalCode – The regional code of the number.
  • countryName – The name of the country where the number is originated.
  • countryCallingCode – The two-digit code of the number.
Job Titles
  • title – The person job title
  • departments – The person departments
  • seniority –  The person seniority

Company

  • logo – The URL of the person’s company logo.
  • description – An overview of the company.
  • domain – The domain of the person’s company.
  • employees – Approximate number of employees in the company.
  • name – The name of the company where the
    person works.
  • website – The website of the company.
  • founders – The names of the company’s founders.
  • founded – The year when the company was founded.

Social

  • facebook.url – Facebook page of the company.
  • linkedin.url – LinkedIn page of the
    company.
  • twitter.url – Twitter page of the company.

HTTP
Request example
GET https://api.lusha.com/person?firstName=Rob&lastName=Taylor&company=intercom


POST https://api.lusha.com/person

{
    “firstName”: :firstName,
    “lastName”: :lastName,
    “organizations”: [
        {
            “company”: :company1,
            “domain”: :domain1,
            “isCurrent“: true
        },
        {
            “company”: :company2,
            “domain”: :domain2,
            “isCurrent“: false
        }
    ]
}


Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{
  "data": {
    "company": {
      "foundedYear": "2011",
      "language": "en",
      "logo": "https://k3f3hfk38ffkkf.lusha.com/af343j1kkv832j925331ff",
      "name": "Intercom",
      "numberOfEmployees": 250,
      "overview": "Intercom is the first to bring messaging products for sales, marketing & customer service to one platform. More than 17,000 businesses use Intercom to connect with a billion people worldwide ",
      "website": "http://intercom.com"
    },
    "emailAddresses": [
      {
        "email": "rtaylor@intercom.io",
        "mailServer": "intercom.io",
        "type": "work"
      },
      {
        "email": "rob.taylor@gmail.com",
        "mailServer": "gmail.com",
        "type": "personal"
      }
    ],
    "location": {
      "country": "United States",
      "country_iso2": "US",
      "continent": "North America",
      "raw_location": "San Francisco, California, United States",
      "state": "California",
      "stateCode": "CA",
      "is_eu_contact": "false",
    },
    "familyName": "Taylor",
    "firstName": "Rob",
    "fullName": "Rob Taylor",
    "phoneNumbers": [
      {
        "countryCallingCode": "1",
        "countryCode": "US",
        "countryName": "United States",
        "internationalNumber": "+1 (212) 480-5911",
        "localizedNumber": "212-480-4076",
        "regionalCode": "212",
      },
      {
        "areaCode": "870",
        "countryCallingCode": "1",
        "countryCode": "US",
        "countryName": "United States",
        "internationalNumber": "+1 (212) 870-4221",
        "localizedNumber": "212-870-4221",
      }
    ],
    "jobTitles": [
      {
        "title": "Human Resources Business Partner",
        "departments": [
          "Human Resources",
          "General Management"
        ],
        "seniority": "Executive"
      }
    ],
    "meta": {
      "matches_this_month": 1
    }
  }
}

Person API V2

The enhanced Bulk Person API V2 offers significant improvements for users. It now supports automatic enrichment based solely on emails or LinkedIn profiles, extending beyond the capabilities previously available in Person API V1. Additionally, it ensures access to the latest contact information, effectively updating even those leads that became outdated after being acquired through marketing campaigns or contact us forms.
 
Note that users can now send a single request to retrieve up to 100 objects from Lusha, with one credit being deducted for each successful match. This feature is particularly beneficial as it minimizes daily API usage, thus optimizing the integration between Lusha API and third-party systems.

 

Endpoint URL:

POST https://api.lusha.com/v2/person -H api_key:API_KEY

Person request schema:

Note: the new request parameters combination is: LinkedIn URL OR email OR Full name + Company name / Company domain

{
 "contacts":[
  {
    "contactId": (required, unique, type string)
    "fullName": (required if linkedinUrl or email not provided, type string),
    "location": (optional, type string),
    "linkedinUrl": (required if fullName or email not provided, type string), 
    "email": (required if fullName or linkedinUrl not provided, type string)
    "companies": (required if fullName provided) 
    [
        {
          "name": (required if "domain" not provided , type string, min_length=2),
          "domain": (required if "name" not provided, type string, min_length=4),
          "isCurrent":  (required, type bool),
          "jobTitle": (optional, type string, min_length=2)
          "fqdn": (optional, type string)
          "companySocialId": (optional, type string)
        }
    ]
  }
 ],
 "metadata":{
   "filterBy": (optional, one of ("emailAddresses", "phoneNumbers")),
   "refreshJobInfo": (optional, boolean, default = false)
 },
}

Request body length: max 100 objects.

HTTP parameters

contacts

Required

contacts

Required

Contact []
array of contact
metadata

Optional

Object

filterBy
For cases when you want to get a hit only in case a phone number for the person exists, you should add the following to the request:
{ metadata: filterBy: “phoneNumbers” }

Alternatively, when you require an email for your results, you should add this:
{ metadata: filterBy: “emailAddresses” }

By default, Lusha returns result for every record that has at least one of them.

refreshJobInfo
Enable this to refresh and use updated job information for the contact, replacing any outdated job details provided. Ideal for retrieving the most recent employment data.

 

Contact parameters
contactId

Required

String
Your contact id identifier to find the contact in the response.
fullName

Required

String
Full name of the person (e.g – Dustin Moskovitz)
location

Optional

String
Raw location of the person – can be country / city / raw location (e.g – Singapore / Chicago)
linkedinUrl

Optional

String
The LinkedIn url of the person
email

Optional

String
The email of the person
companies

Required

ContactCompany []
Company

 

Contact Company
name

Required

String
The name of the company (e.g – Lusha)
domain

Optional

String
The domain name (e.g – lusha.com)
isCurrent

Required

Boolean
Last company of the person (e.g – true)
jobTitle

Optional

String
The contact jobTitle at the current company
fqdn

Optional

String
The fqdn name (e.g – lusha.com)
companySocialId

Optional

String
The social id if the company

Person/Company API
Person response schema:
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
{
    "contacts": {
        "99b456090248e-d6f5-49ea-83e1-99b4c8ade38d": {
            "error": null,
            "isCreditCharged": true,
            "data": {
                "firstName": "Max",
                "lastName": "Shapiro",
                "fullName": "Max Shapiro",
                "companyId": 16272,
                "emails": [
                    "max.shapiro@zoominfo.com"
                ],
                "phones": [
                    "(415)887-1172"
                ],
                "location": {
                    "state": "Georgia",
                    "country": "United States",
                    "country_iso2": "US",
                    "continent": "North America",
                    "raw_location": "Atlanta, Georgia, United States"
                },
                "jobTitle": {
                    "seniority": "Other",
                    "seniorityLabels": [
                        {
                            "id": 1,
                            "value": "other"
                        }
                    ],
                    "title": "Enterprise Account Executive , Operationsos",
                    "departments": [
                        "Sales"
                    ]
                },
                "socialLinks": {
                    "linkedin": "https://www.linkedin.com/in/maxjshapiro"
                },
                "jobStartDate": "2023-07-01",
                "previousJob": {
                    "company": {
                        "name": "Stealth",
                        "domain": "stealthstartup.com"
                    },
                    "jobTitle": {
                        "title": "Data Consultant",
                        "departments": [
                            "Consulting",
                            "Research & Analytics",
                            "Engineering & Technical"
                        ],
                        "seniority": "Other"
                    }
                }
            }
        }
    },
    "companies": {
        "16272": {
            "name": "ZoomInfo",
            "description": "ZoomInfo (NASDAQ: ZI) is a leader in modern go-to-market software, data, and intelligence for more than 30,000 companies worldwide. \n\nZoomInfo's revenue operating system, RevOS, empowers business-to-business sales, marketing, operations, and recruiting professionals to hit their number by pairing best-in-class technology with unrivaled data coverage, accuracy, and depth of company and contact information. With integrations embedded into workflows and technology stacks, including the leading CRM, Sales Engagement, Marketing Automation, and Talent Management applications, ZoomInfo drives more predictable, accelerated, and sustainable growth for its customers. ZoomInfo emphasizes GDPR and CCPA compliance. In addition to creating the industry's first proactive notice program, the company is a registered data broker with the states of California and Vermont. \n\nFor more information about ZoomInfo's leading go-to-market software, data, and intelligence, and how they help sales, marketing, operations, and recruiting professionals, please visit www.zoominfo.com.",
            "domains": {
                "homepage": "zoominfo.com",
                "email": "zoominfo.com"
            },
            "homepageUrl": "http://zoominfo.com",
            "fqdn": "www.zoominfo.com",
            "location": {
                "city": "Vancouver",
                "continent": "North America",
                "country": "United States",
                "rawLocation": "805 Broadway St, Vancouver, Washington 98660, US",
                "countryIso2": "US",
                "state": "Washington",
                "stateCode": "WA",
                "street": "805 Broadway St",
                "locationCoordinates": [
                    -122.66149,
                    45.63873
                ]
            },
            "companySize": [
                1001,
                5000
            ],
            "revenueRange": [
                500000000,
                1000000000
            ],
            "industryPrimaryGroup": "Software Development",
            "logoUrl": "https://logo.lusha.co/d/company_16272_logo.jpg",
            "social": {
                "linkedin": "https://www.linkedin.com/company/zoominfo",
                "crunchbase": "https://www.crunchbase.com/organization/zoominfo"
            },
            "specialities": [
                "marketing intelligence",
                "database hygiene",
                "lead generation",
                "data orchestration",
                "improved prospecting",
                "data accuracy",
                "sales intelligence",
                "business information",
                "contact data"
            ]
        }
    }
}

Company API

The company API provides information about any organization you look for to help you get a complete picture, such as overview, social network presence and location.

HTTP request

GET https://api.lusha.com/company?domain=:domain

(Where :domain is the domain of the company)

For each request, Lusha returns your current usage status under the “meta” tag

HTTP parameters

company

Required if domain is not provided

The name of the company (e.g – Lusha)
domain

Required if company is not provided

The domain name (e.g – lusha.com)

Company Attributes

  • logo – Company’s logo URL.
  • name – Name of company.
  • website – URL of the company’s website.
  • language – Language of the website.
  • numberOfEmployees – Approximate number of employees.
  • foundedYear – The year when the organization was founded.
  • overview – Description of the company.

Location

  • fullLocation – Full representation of the location.
  • timeZone – Current time zone based on the company’s location.
  • utcOffset – UTC offset of the company’s location.
  • city – The city where the company resides.
  • state – Full text of the company’s state.
  • stateCode – Two digit code of the company’s state.
  • country – The country where the company is located.
  • countryCode – Two digit code of the company’s country.
  • latitude – The approximate latitude based on the location info.
  • longitude – The approximate longitude based on the location info.

Facebook

  • url – URL of Facebook page of the company.
  • bio – Facebook bio of the company.

Twitter

  • url – URL of Twitter page of the company.
  • bio – Bio of the company’s Twitter page.
  • following – Number of people that the page follows.
  • followers – Number of people that follow the page.

Crunchbase

  • url – URL of the company’s Crunchbase page.
  • bio – Crunchbase’s overview of the company.

Linkedin

  • url – URL of the company’s LinkedIn page.
  • bio – Overview of the company from LinkedIn.

Traffic

  • rank – The ranking of the website’s incoming traffic in a specific region.
  • region – The region where the ranking is measured.

Request example:
curl "https://api.lusha.com/company?domain=intercom.com" -H "api_key:YOUR_API_KEY"


Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"data": {
   "description": "A fundamentally new way to communicate with your customers",
   "domain": "intercom.com",
   "employees": "101 - 250",
   "founded": "August 1, 2011",
   "founders": "Ciaran Lee, Eoghan McCabe, David Barrett, Des Traynor",
   "logo": "https://images.lusha.com/ImludGVyY29tL2NiTG9nby5wbmci.K1Pu8jup9e0-1KkYVsDBNv30ddo",
   "name": "Intercom",
   "social": {
      "facebook": {
         "url": "http://www.facebook.com/intercominc"
      },
      "linkedin": {
         "url": "http://www.linkedin.com/company/2491343"
      },
      "twitter": {
         "url": "http://twitter.com/intercom"
      }
   },
   "website": "http://www.intercom.com"
},
"meta": {
   "matches_this_month": 2
}

Prospecting API

With Lusha’s Prospecting API, you can query Lusha’s database based on specific criteria (job title, seniority, location, and more), and receiving the rest of the contact information with his connect information.

Prospecting API helps to increase your net new records (contacts/leads), either for your existing CRM accounts or for new accounts, based on your ICP filters.

The process for retrieving contact information includes 3 main stages:

  1. Select and apply the filters you would like to use.
  2. Search relevant contacts.
  3. Enrich contacts by revealing contacts full details.

In this guide, we will describe every stage in detail.

Pay attention! The header of API KEY is mandatory in every request to our service!

Prospecting filtering options

Several fields are requesting specific values or ranges which can be revealed by using the filters API. By adding the filter name and requested data, a user can receive the possible values and send them to the prospecting search API as described earlier.

Endpoint URL (for specific filters):

https://api.lusha.com/prospecting/filters/contacts || companies/filter name

Specific Filters (Retrieving from the Endpoint URL)


Companies filters

HTTP Request
Response
POST
/companies/names
body:
{
“text”: “lusha”
}
[
{
“companyId”: 33222678,
“logoUrl”: “http://lusha.com/logo.jpg”,
“name”: “Lusha”,
“fqdn”: “www.lusha.com”
},
]
GET
/companies/industries
[
{
“value”: “accounting”,
“label”: “Accounting”,
},

]
GET
/companies/sizes
[
{
“min”: “1”,
“max”: “10”,
},

]
GET
/companies/revenues
[
{
“min”: “1”,
“max”: “1000000”,
},

]
POST
/companies/locations
Body:
{
“text”: “isr”
}
[
{
“id”: “1723”,
“country_grouping”: “emea”,
“continent”: “Asia”,
“country”: “Israel”,
“key”: “country”,
},
]
GET
/companies/sics
[
{
“code”: “1011”,
“label”: “iron ores”,
},
]
GET
/companies/naics
[
{
“code”: “1141”,
“label”: “fishing”,
},
]
GET
/companies/industries_labels
[
{
“main_industry”: “Hospitality”,
“main_industry_id”: 1,
“sub_industries”: [
{
“value”: “Restaurants”,
“id”: 2
},
{
“value”: “Food & Beverage Services”,
“id”: 1
},
{
“value”: “Hotels & Motels”,
“id”: 3
}
]
},
]



Contacts filters:

HTTP Request
Response
POST
/contacts/job_titles
body:
{
“text”: “developer”
}
[
“software developer”,
“developer”,
“website developer”,
“frontend developer”,

]
GET
/contacts/departments
[
“Business Development”,
“Consulting”,
“Customer Service”,

]
GET
contacts/seniority
[
{
“code”: “5”,
“label”: “Manager”,
},
]
GET
contacts/existing_data_points
[
{
“phone”,
“email”,
“work_email”,
},
]
GET
/contacts/all_countries
[
{
“name”: “United States”,
“code”: “US”,
},
]
POST
/contacts/locations
Body:
{
“text”: “un”
}
[
{
“continent”: “North America”,
“country”: “United States”,
},
]

Search contacts

(prospecting/contact/search)

This is the first stage in getting contacts or companies based on a query sent to Lusha’s system. In the case of contacts, the response includes indications per contact whether the information exists (or doesn’t exist) in Lusha (for example, does the contact have email addresses or phone numbers?)

Endpoint URL:

POST https://api.lusha.com/prospecting/contact/search -H api_key:API_KEY

The request for search contacts is mainly based on the filters which were mentioned earlier. The filters can be used as “include” and “exclude” options and behave as an “OR” action between them (union between them). For a search request, one must provide at least one filter.

The filters for search are described as following:

Contact Filters
Field

Description and Example
names
Array of Strings (Free Text)
Names of contacts (e.g. – “Laura”)
jobTitles
Array of Strings (Free Text)
Job titles of contacts (e.g. – “creative”)
countries
Array of Strings (Closed List)
Based on specific filter filters/contact/countries
Country Codes of contacts (e.g. – “US”, “GB”)
seniority
Array of IDs (Closed List)
Based on specific filter filters/contact/seniority
Senioritis (e.g. 5 for “Manager”)
Departments
Array of Strings (Closed List)
Based on specific filter filters/contact/departments
Departments (e.g. “Product”)
existingDataPoints
Array of Strings (Closed List)
Based on specific filter filters/contact/existing_data_points
Filter contacts who have this data point (e.g. “work_email”)
Company Filters
Field

Description and Example
companyIds
Array of Integers (Closed List)
Based on specific filter filters/companies/names
Lusha’s Ids companies (e.g. – 1586 for “Amazon”)
names
Array of Strings (Free Text)
Names of companies (e.g. – Amazon)
domains
Array of Strings (Free Text)
Domains of companies (e.g. – amazon.com)
industries
Array of Strings (Closed List)
Based on specific filter filters/companies/industries
Industries (e.g. – internet publishing)
locations
(company’s HQ locations)
Array of Objects – Location Object
Based on specific filter filters/companies/locations
Company’s HQ locations.
City, State, Country and Continent.
sizes
Array of Objects – Range Object
Based on specific filter filters/companies/sizes
Min and Max for company size.
revenues
Array of Objects – Range Object
Based on specific filter filters/companies/revenues
Min and Max for the company’s revenue.
industrySics
Array of Integers (Closed List)
Based on specific filter filters/companies/sics
Codes of sics (e.g. – 1011)
industryNaics
Array of Integers
Based on specific filter filters/companies/naics
Codes of naics (e.g. – 1141)
HTTP Parameters
pages

Getting offset for results
Object
page – integer between 0-1000 (default: 0)
size – integer between 10-40 (default: 20)
filters

Filtering for prospecting contacts or companies.
Object
contacts: {
include: ContactFilters (described),
exclude: ContactFilters (described)
}companies: {
include: CompanyFilters (described),
exclude: CompanyFilters (described)
}

 

Example - Search contacts
Enrich CRM accounts with contacts
Get a list of existing accounts from your CRM/customer database, so that you can attract new contacts/leads who fit your targeted persona (job title, seniority, department). E.g List of directors from Engineering & Technical department working in Amazon, Google, Microsoft, Apple, IBM, Tesla, etc.
The Request
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "pages": { "page": 0, "size": 25 },
   "filters": {
       "contacts": {
           "include": {
               "departments": ["Engineering & Technical"],
               "seniority": [6]
           }   
       },
       "companies": {
           "include": {
               "names": ["Apple", "Amazon", "Google", "Microsoft",
               "IBM",  "HSBC", "Accenture", "Deloitte",
               "Tesla", "Facebook",  "Nike", 
               "Procter & Gamble", "Walmart", "PepsiCo", "EY"
               ],
               "mainIndustriesIds": [1],
               "subIndustriesIds": [1,2,3], // must come with main industries ids filter (mainIndustriesIds)
           }
       }
   }
}

The Response
The response includes the requestId and the contacts which are addressed to filters query. It’s important to use the requestID and contactIDs in order to send them for enrichment in the next endpoint.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
   "requestId": "e31c4667-3ac0-4e13-96cf-a7d3ae4ae37a",
   "currentPage": 0,
   "pageLength": 25,
   "totalResults": 5846,
   "data": [
       {
           "contactId": "26a668f0-9ce4-11ed-8073-5eb64d7323e5",
           "isShown": false,
           "name": {
               "first": "Brian",
               "last": "Tuskan",
               "full": "Brian Tuskan"
           },
           "jobTitle": "■ Chief Security Officer Senior Director Global Physical Security @ Microsoft Corporation",
           "companyId": 1035,
           "companyName": "Microsoft",
           "hasDepartment": true,
           "hasSeniority": false,
           "hasContactLocation": true,
           "hasSocialLink": true,
           "hasEmails": true,
           "hasPhones": false,
           "hasCompanyCity": true,
           "hasCompanyCountry": true
       },
       {
           "contactId": "26a668f1-9ce4-11ed-9fdf-f19bede8a276",
           "isShown": false,
           "name": {
               "first": "Virginie",
               "last": "Henry",
               "full": "Virginie Henry"
           },
           "jobTitle": "Chief Strategy Officer ( Chief Security Officer ) Program Leader and Experience Director",
           "companyId": 1038,
           "companyName": "Deloitte",
           "hasDepartment": true,
           "hasSeniority": false,
           "hasContactLocation": true,
           "hasSocialLink": true,
           "hasEmails": true,
           "hasPhones": true,
           "hasCompanyCity": false,
           "hasCompanyCountry": false
       },
   ]
}

Discover new companies and contacts based on ICP filters
Get a list of contacts/companies, using target audience filters (industry, location, employee count, title, etc.)
E.g List of CISO in the US for companies with 200+ employees
The Request
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
   "pages": { "page": 0, "size": 25 },
   "filters": {
       "contacts": {
           "include": {
               "jobTitles": ["ciso"]
           }   
       },
       "companies": {
           "include": {
               "sizes":[{ "min": 201,  "max": 500 },
                        { "min": 501,  "max": 1000 },
                        { "min": 1001,  "max": 5000 },
                        { "min": 5001,  "max": 10000 },
                        { "min": 10001 }],
               "locations": [{
                   "country": "United States",
                   "continent": "North America"
               }]
           }
       }
   }
}

The Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{ 
  "requestId": "48ab02c7-1784-4ca6-b5ad-4fcf164474c9",
   "currentPage": 0,
   "pageLength": 25,
   "totalResults": 1332,
   "data": [
       {
           "contactId": "44d0a910-9ce6-11ed-bbe0-70ee5d0e02c0",
           "isShown": false,
           "name": {
               "first": "Josh",
               "last": "Lemos",
               "full": "Josh Lemos"
           },
           "jobTitle": "Chief Information Security Officer ( Ciso )",
           "companyId": 675562,
           "companyName": "Square",
           "hasDepartment": true,
           "hasSeniority": false,
           "hasContactLocation": true,
           "hasSocialLink": true,
           "hasEmails": true,
           "hasPhones": true,
           "hasCompanyCity": true,
           "hasCompanyCountry": true
       },
       {
           "contactId": "44d0a911-9ce6-11ed-9e7f-e37170d93e43",
           "isShown": false,
           "name": {
               "first": "Brian",
               "last": "Owens",
               "full": "Brian Owens"
           },
           "jobTitle": "Ciso and Head of Infrastructure",
           "companyId": 1497977,
           "companyName": "Murphy USA",
           "hasDepartment": true,
           "hasSeniority": false,
           "hasContactLocation": true,
           "hasSocialLink": true,
           "hasEmails": true,
           "hasPhones": true,
           "hasCompanyCity": true,
           "hasCompanyCountry": true
       },
]

Enrich contacts

(prospecting/contact/enrich)

The Enrich API provides information about requested contacts. It includes the consumption of credits for showing contact details (only for the first time of the account).

Endpoint URL:

POST https://api.lusha.com/prospecting/contact/enrich -H api_key:API_KEY

 

HTTP parameters

requestId

(required)

The request Id as sent in the search response.
UUID
contactIds

(required)

The ID of the contact for enrichment (sent in the search response for every contact).
Array of Strings

 

Example - Enrich contacts
Request example:
The body parameters include two main fields (which were received in the search request earlier). The “requestId” of the search request and an array of contacts (represented by their IDs) that the user asks for their full information. Notice that in every enrichment request, there is a limitation of max. 30 contacts.
1
2
3
4
{
   "requestId":"8a8064bd-082e-4114-b298-269ac35d20ee",
   "contactIds":["8cc2fb7c-b080-4994-b64b-6d623b8b2d36", "68e5f6e2-2190-4f8b-8853-b8967e8f438e"]
}

The response
The response includes the requested contacts with their full details.
Response example
Following our example of a contact with the name of “Laura”, below is a possible response for this contact. The response includes the full details of the contact.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "requestId": "7a43372e-5877-4ab6-ab68-e08c2535a385",
  "contacts": [
    {
      "id": "a1a96c20-b5b0-11ed-b1a6-90e6add27791",
      "isSuccess": true,
      "data": {
        "firstName": "Jessica",
        "lastName": "Test",
        "fullName": "Jessica Test",
        "isShown": false,
        "jobTitle": "Global Senior Director , Industry Marketing + Chief Creative Officer",
        "emailAddresses": [
          {
            "email": "test1@microsoft.com"
          },
          {
            "email": "test2@live.com"
          }
        ],
        "phoneNumbers": [
          {
            "number": "+1 123-445-6789"
          },
          {
            "number": "+1 456-452-2111"
          }
        ],
        "companyId": 1035,
        "companyName": "Microsoft",
        "socialLinks": {
          "linkedin": "https://www.linkedin.com/in/test"
        },
        "departments": [
          "Marketing",
          "Product"
        ],
        "seniority": [
          "Executive"
        ],
        "contactLocation": "Redmond, Washington, United States"
      }
    }
  ]
}
Search companies

(prospecting/company/search)

Endpoint URL:

POST https://api.lusha.com/prospecting/company/search -H api_key:API_KEY

The request for search companies is mainly based on the filters which were mentioned earlier. The filters can be used as “include” and “exclude” options and behave as an “OR” action between them (union between them). For a search request, one must provide at least one filter.

HTTP parameters

pages

Getting offset for results
Object

page – integer between 0-1000 (default: 0)
size – integer between 10-40 (default: 20)
filters

Filtering for prospecting contacts or companies.
Object

contacts: {
include: ContactFilters (described),
exclude: ContactFilters (described)
}companies: {
include: CompanyFilters (described),
exclude: CompanyFilters (described)
}

The Response
The response includes the requestId and the companies which are addressed to filters query. It’s important to use the requestID and companiesIDs in order to send them for enrichment in the next endpoint.

Example - Search companies
Request example
In this example, we would like to prospect specific companies in the Manufacturing industry in UK
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
   "pages": {
       "page": 0,
       "size": 40
   },
   "filters": {
       "companies": {
           "include": {
               "industries": [77],
               "locations": [{"continent": "Europe", 
                              "country": "United Kingdom"}]
           }
       }
   }
}

The response of the search request includes several technical details such as the ID of the request, the page details (for pagination), current page and its length (the number of companies in the current response), and the total results.
Every company in the response reveals the company ID (which will be used later for enrichment), and their name.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "requestId": "8a8064bd-082e-4114-b298-269ac35d20ee",
    "currentPage": 1,
    "pageLength": 25,
    "totalResults": 2,
    "data": [
        {
            "id": "2026",
            "name": "test1"
        },
        {
            "id": "16743",
            "name": "test2"
        }
    ]
}

Enrich companies

(prospecting/company/enrich)

Endpoint URL:

POST https://api.lusha.com/prospecting/company/enrich -H api_key:API_KEY

 

HTTP parameters

requestId

(required)

The requestId as sent in the search response.
UUID
companiesIds

(required)

The ID of the company for enrichment (sent in the search response for every company).
Array of Strings

 

Possible errors

wrong or not found requestId

Verify that the requestId matches to the requestId in the response
wrong or not found companiesIds

Verify that the companiesIds match to the companiesIds in the response
insufficient amount of credits for the requesting account

Ask for additional credits

Example - Enrich companies
Request example
The body parameters include two main fields (which were received in the search request earlier). The “requestId” of the search request and an array of companies (represented by their IDs) that the user asks for their full information. Notice that in every enrichment request, there is a limitation of max. 30 companies.
1
2
3
4
{
 "requestId": "be06d317-5e01-43a9-a4d3-3947961b0e19",
 "companiesIds": ["2291"]
}

The Response
The response includes the requested companies with their full details.
Request example
Following our example of a company with the name of “Test1”, below is a possible response for this company. The response includes the full details of the company.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "requestId": "8a8064bd-082e-4114-b298-269ac35d20ee",
    "currentPage": 1,
    "pageLength": 25,
    "totalResults": 2,
    "data": [
        {
            "id": "2026",
            "name": "test1"
        },
        {
            "id": "16743",
            "name": "test2"
        }
    ]
}

Legal Guidelines

We work diligently to comply with applicable laws and strive to safeguard individual rights. Thus, we require you to specify for what purpose you obtain our data in order to inquire if the purpose is lawful.

In addition, we specified hereunder important guidelines which applicable to all our API customers and we request that you shall respect them:

a. You shall agree to the terms of our API Agreement and our Privacy Policy.
b. You should not violate privacy rights or intellectual property rights of any third party.
c. You should not use our data for purposes of cookie tracking, ad exchanges, ad networks, data brokerages, SPAM or any other purpose in violation of any applicable law.
d. You shall use our data in compliance with applicable data privacy and protection laws.
e. You shall take adequate security measures to safeguard personally identifiable information you receive from us.
f. You shall respect individuals’ privacy rights and delete personally identifiable information you obtain from us, in case you receive a notification from an individual requiring that you shall delete it.
g. You shall take measures to guarantee that you have the right to upload and share with us information relating to individuals.