Contact API Examples & Docs - Enrich Leads Programmatically

API

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 request 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. Each match is counted, even when it’s a duplicate.

Lusha API endpoint

https://api.lusha.co/

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.co/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 Too many requests – You’ve surpassed your usage limits. You may want to contact us and upgrade your plan
  • 404 Not found – The requested endpoint was not found
  • 429 Limit reached – You’ve reached your trial limit, please contact support for upgrade
  • 5XX Server error – There’s a problem on Lusha’s end

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.co/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.co/person?
firstName=:firstName&lastName=:lastName&company=:company
&property=phoneNumbers

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)

HTTP request example

GET https://api.lusha.co/person?
firstName=Rob&lastName=Taylor&company=intercom

Response

"data": {
   "company": {
      "foundedYear": "2011",
      "language": "en",
      "logo": "https://k3f3hfk38ffkkf.lusha.co/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": {
      "city": "San Francisco",
      "country": "United States",
      "countryCode": "US",
      "fullLocation": "San Francisco, CA, US",
      "lat": 37.7749295,
      "lng": -122.4194155,
      "state": "California",
      "stateCode": "CA",
      "timeZone": "America/Los_Angeles",
      "utcOffset": -7
   },
   "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",
         "type": "work"
      },
      {
         "areaCode": "870",
         "countryCallingCode": "1",
         "countryCode": "US",
         "countryName": "United States",
         "internationalNumber": "+1 (212) 870-4221",
         "localizedNumber": "212-870-4221",
         "type": "personal"
      }
   ]
},
"meta": {
   "matches_this_month": 1
}

Person Attributes

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

Location
fullLocation – Full representation of the location.
timeZone – Current time zone based on the person’s location.
utcOffset – UTC offset of the person’s location.
city – The city where the person lives.
state – Full text of the person’s state.
stateCode – Two digit code of the person’s state.
country – The country where the person lives.
countryCode – Two digit code of the person’s country.
latitude – The latitude we surmised from the location info we have.
longitude – The longitude we surmised from the location info we have.

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.
type – The type of the phone number. It might be work, mobile or other.

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.

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.co/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.co)

Example request

curl “https://api.lusha.co/company?domain=intercom.com” -H “api_key:YOUR_API_KEY”

Response

"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.co/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
}

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.

Email Address
email – The main email of the company.
mailServer – The mail server of the company.

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.

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 incoming traffic in a specific region.
region – The region where the ranking is measured.

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.