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.
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.
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
RateLimit-Remaining
RateLimit-Reset
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 |
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
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.
contactId
Required
Your contact id identifier to find the contact in the response.
firstName
Required
First name of the person (e.g – Dustin)
lastName
Required
Last name of the person (e.g – Moskovitz)
location
Optional
Raw location of the person – can be country / city / raw location (e.g – Singapore / Chicago)
linkedinUrl
Optional
The LinkedIn url of the person
companies
Required
Company
name
Required
The name of the company (e.g – Lusha)
domain
Optional
The domain name (e.g – lusha.com)
isCurrent
Required
Last company of the person (e.g – true)
jobTitle
Optional
The contact jobTitle at the current company
fqdn
Optional
The fqdn name (e.g – lusha.com)
companySocialId
Optional
The social id if the company
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
array of Company to search for
Id
Required
Your company identifier to find the company in the response.
name
Required if domain/fqdn is not provided
The name of the company (e.g – Lusha)
domain
Required if name/fqdn is not provided
The domain name (e.g – Lusha.com)
fqdn
Required if name/domain is not provided
The fqdn name (e.g – Lusha.com)
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
lastName
Required
company
Required if domain is not provided
domain
Required if company is not provided
linkedinUrl
Optional
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.
- 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.
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
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.
contactId
Required
Your contact id identifier to find the contact in the response.
fullName
Required
Full name of the person (e.g – Dustin Moskovitz)
location
Optional
Raw location of the person – can be country / city / raw location (e.g – Singapore / Chicago)
linkedinUrl
Optional
The LinkedIn url of the person
Optional
The email of the person
companies
Required
Company
name
Required
The name of the company (e.g – Lusha)
domain
Optional
The domain name (e.g – lusha.com)
isCurrent
Required
Last company of the person (e.g – true)
jobTitle
Optional
The contact jobTitle at the current company
fqdn
Optional
The fqdn name (e.g – lusha.com)
companySocialId
Optional
The social id if the company
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
domain
Required if company is not provided
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.
- url – URL of Facebook page of the company.
- bio – Facebook bio of the company.
- 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.
- 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.
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:
- Select and apply the filters you would like to use.
- Search relevant contacts.
- 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
/companies/names
body:
{
“text”: “lusha”
}
{
“companyId”: 33222678,
“logoUrl”: “http://lusha.com/logo.jpg”,
“name”: “Lusha”,
“fqdn”: “www.lusha.com”
},
]
/companies/industries
{
“value”: “accounting”,
“label”: “Accounting”,
},
…
]
/companies/sizes
{
“min”: “1”,
“max”: “10”,
},
…
]
/companies/revenues
{
“min”: “1”,
“max”: “1000000”,
},
…
]
/companies/locations
Body:
{
“text”: “isr”
}
{
“id”: “1723”,
“country_grouping”: “emea”,
“continent”: “Asia”,
“country”: “Israel”,
“key”: “country”,
},
]
/companies/sics
{
“code”: “1011”,
“label”: “iron ores”,
},
]
/companies/naics
{
“code”: “1141”,
“label”: “fishing”,
},
]
/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:
/contacts/job_titles
body:
{
“text”: “developer”
}
“software developer”,
“developer”,
“website developer”,
“frontend developer”,
…
]
/contacts/departments
“Business Development”,
“Consulting”,
“Customer Service”,
…
]
contacts/seniority
{
“code”: “5”,
“label”: “Manager”,
},
]
contacts/existing_data_points
{
“phone”,
“email”,
“work_email”,
},
]
/contacts/all_countries
{
“name”: “United States”,
“code”: “US”,
},
]
/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:
Field
Names of contacts (e.g. – “Laura”)
Job titles of contacts (e.g. – “creative”)
Based on specific filter filters/contact/countries
Country Codes of contacts (e.g. – “US”, “GB”)
Based on specific filter filters/contact/seniority
Senioritis (e.g. 5 for “Manager”)
Based on specific filter filters/contact/departments
Departments (e.g. “Product”)
Based on specific filter filters/contact/existing_data_points
Filter contacts who have this data point (e.g. “work_email”)
Field
Based on specific filter filters/companies/names
Lusha’s Ids companies (e.g. – 1586 for “Amazon”)
Names of companies (e.g. – Amazon)
Domains of companies (e.g. – amazon.com)
Based on specific filter filters/companies/industries
Industries (e.g. – internet publishing)
(company’s HQ locations)
Based on specific filter filters/companies/locations
Company’s HQ locations.
City, State, Country and Continent.
Based on specific filter filters/companies/sizes
Min and Max for company size.
Based on specific filter filters/companies/revenues
Min and Max for the company’s revenue.
Based on specific filter filters/companies/sics
Codes of sics (e.g. – 1011)
Based on specific filter filters/companies/naics
Codes of naics (e.g. – 1141)
pages
Object
page – integer between 0-1000 (default: 0)
size – integer between 10-40 (default: 20)
filters
Object
contacts: {
include: ContactFilters (described),
exclude: ContactFilters (described)
}companies: {
include: CompanyFilters (described),
exclude: CompanyFilters (described)
}
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)
UUID
contactIds
(required)
Array of Strings
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
Object
page – integer between 0-1000 (default: 0)
size – integer between 10-40 (default: 20)
filters
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.
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)
UUID
companiesIds
(required)
Array of Strings
Possible errors
wrong or not found requestId
wrong or not found companiesIds
insufficient amount of credits for the requesting account
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.