Overview

Introduction

API Endpoint

https://api.uplead.com/v2/

Welcome to UpLead’s API! You can use this API to access all our API endpoints.
Our main calls are:

Company API

Person API

Combined API

Prospector API

Prospector Pro API

Company Logo API

Company Name to Domain API

Authentication

To authorize, use this code:

curl "https://api.uplead.com/v2/api_endpoint_here"
  -H "Authorization: myapikey"

Authentication is made with your API Key which can be found in your account settings.

You will have to add your API Key to every call you make to our API. This parameter is always required. We'll return an error if the key is either missing or invalid.

Your API key is what identifies your account, so be sure to keep it secret! Please don’t share it with anyone outside of your organization.

Authorization: myapikey

Errors

Our API uses conventional HTTP response codes to indicate the success or failure of an API request.

In case of an error, we will return the correspondent error code.

HTTP Status codes

Error Code Meaning
400 Bad Request -- Your parameters are invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Your account is on pause or you don't have a subscription.
429 Too Many Requests -- You're making too many requests.
50X Internal Server Error -- We had a problem with our server. Try again later.

Rate Limit

Example rate limit error response:

HTTP/1.1 429 Too Many Requests

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1402010983
Retry-After: 50

Content-Type: application/json

{
    "error": {
          "type": "rate_limit",
          "message": "Rate limit exceeded. Limit is 500 requests per minute. Rate limit 
                                will be reset in 50 seconds."
    }
}

You can make 500 requests per minute to the API.

Check the returned HTTP headers of any API request to see your current rate limit status.

Header Name
X-RateLimit-Limit The maximum number of requests that the customer is permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
Retry-After The number of seconds to wait until the rate limit window resets. Only sent when the rate limit.

Billing

One credit will be deducted for each contact or company record that you receive.

You will not be charged twice for the same contact/company record.

For contact records that include an email address: A credit will only be deducted for a contact if the response code comes back as “Valid” or “Accept All” (email_status).

Credits

Response:

{
    "data": {
        "email": "john@uplead.com",
        "credits": "100"
    }
}

This endpoints allows you to get information about your remaining credits.

Example Request

GET/POST

https://api.uplead.com/v2/credits

Company API

Response:

{
    "data": {  
        "id": "9c7a4e17-9090-4293-a74b-05b0d0e34516",
        "company_name": "Amazon.com, Inc.",
        "domain": "amazon.com",
        "address": "410 Terry Ave N",
        "city": "Seattle",
        "state": "WA",
        "zip": "98109",
        "country": "United States",
        "county": "King",
        "phone_number": "2062661000",
        "fax_number": "3026365454",
        "employees": "Over 10,000",
        "revenue": "Over $1 Billion",
        "industry": "Retail",
        "sic_code": 5961,
        "sic_description": "Catalog and Mail-Order Houses",
        "naics_code": 45411,
        "naics_description": "Electronic Shopping and Mail-Order Houses",
        "description": "Amazon.com, Inc. offers a range of products and services through
its Websites. The Company operates through three segments: North America, 
International and Amazon Web Services (AWS). The Company's products include 
merchandise and content that it purchases for resale from vendors and those 
offered by third-party sellers. It also manufactures and sells electronic 
devices. The Company, through its subsidiary, Whole Foods Market, Inc., 
offers healthy and organic food and staples across its stores. 
The Company also offers a range of products like whole trade bananas, 
organic avocados, organic large brown eggs, organic responsibly-farmed 
salmon and tilapia, organic baby kale and baby lettuce, 
animal-welfare-rated 85% lean ground beef, creamy and crunchy almond 
butter, organic gala and fuji apples, organic rotisserie chicken.",
        "year_founded": 1994,
        "logo": "https://logo.uplead.com/amazon.com",
        "linkedin_url": "https://www.linkedin.com/company/amazon",
        "twitter_url": "https://twitter.com/amazon",
        "facebook_url": "https://www.facebook.com/Amazon",
        "youtube_url": "https://www.youtube.com/user/amazon",
        "crunchbase_url": "https://www.crunchbase.com/organization/amazon",
        "yelp_url": "",
        "instagram_url": "https://www.instagram.com/amazon/",
        "type": "Public",
        "ticker": "AMZN",
        "exchange": "Nasdaq",
        "alexa_rank": 10
    }
}

Our Company API lets you lookup company data via a domain name or company name. You get a full overview of the company including size, location, social links, description, and more. For precise results it’s recommended to use a domain name.

Example Request

GET

https://api.uplead.com/v2/company-search?domain=amazon.com


POST

https://api.uplead.com/v2/company-search

Request JSON body:

{ "domain": "amazon.com" }

Parameters

Parameter Description
company Required if domain is not provided
the name of the company (e.g – amazon)
string
domain Required if company is not provided
the domain name (e.g – amazon.com)
string

Attributes

Attribute Description
id string
internal company id
company_name string
name of the company
domain string
company website url
address string
hq address
city string
hq city name
state string
hq state name
zip string
hq zip code
country string
hq country name
county string
hq county name
phone_number string
company phone number
fax_number string
company fax number
employees string
employees range (1 - 10, 10 - 50, 50 - 200, 200 - 500, 500 - 1,000, 1,000 - 5,000, 5,000 - 10,000, Over 10,000)
revenue string
revenue range (0 - $1 Million, $1 Million - $10 Million, $10 Million - $50 Million, $50 Million - $100 Million, $100 Million - $200 Million, $200 Million - $1 Billion, Over $1 Billion)
industry string
company industry name
sic_code integer
company sic code
sic_description string
company sic code industry description
naics_code integer
company naics code
naics_description string
company naics code industry description
description string
company description
year_founded integer
company year founded
logo string
company logo url
linkedin_url string
company linkedin url
twitter_url string
company twitter url
facebook_url string
company facebook url
youtube_url string
company youtube url
crunchbase_url string
company crunchbase url
yelp_url string
company yelp url
instagram_url string
company instagram url
type string
company type (private, public, education, government, non-profit)
ticker string
company stock ticker
exchange string
company stock exchange
alexa_rank integer
company website alexa ranking

Person API

Response:

{
    "data": {
        "id": "d98e157e-c31d-40a0-9d98-b2fb8390797d",
        "first_name": "marc",
        "last_name": "benioff",
        "title": "ceo",
        "job_function": "",
        "management_level": "c_level",
        "gender": "male",
        "email": "mbenioff@salesforce.com",
        "email_status": "valid",
        "phone_number": "4159017000",
        "city": "San Francisco",
        "state": "CA",
        "country": "United States",
        "linkedin_url": "https://www.linkedin.com/in/marcbenioff/",
        "industry": "Internet",
        "domain": "salesforce.com",
        "company_name": "Salesforce.com, Inc."
    }
}

Our Person API lets you lookup a person based on an email address OR based on a domain name + first name + last name. You get a full overview of the person including name, location, email, phone number, social links and more.

Example Request

GET

https://api.uplead.com/v2/person-search?email=mbenioff@salesforce.com


POST

https://api.uplead.com/v2/person-search

Request JSON body:

{ "email": "mbenioff@salesforce.com" }

Parameters

Parameter Description
email Required if first name + last name + domain is not provided
email address (e.g – mbenioff@salesforce.com)
string
first_name Required if email address is not provided
first name of the person (e.g – Marc)
string
last_name Required if email address is not provided
last name of the person (e.g – Benioff)
string
domain Required if email address is not provided
the domain name (e.g – salesforce.com)
string

Attributes

Attribute Description
id string
internal person id
first_name string
person first name
last_name string
person last name
title string
person job title
job_function string
person job function
management_level string
person management level (M level, D level, VP level, C level)
gender string
person gender
email string
person email address
email_status string
person email address status code
phone_number string
company phone number
city string
person city
state string
person state
country string
person country
linkedin_url string
person linkedin url
industry string
company industry name
domain string
company domain url
company_name string
company name

Combined API

(Person + Company)

Response:

{
    "data": {
        "id": "d98e157e-c31d-40a0-9d98-b2fb8390797d",
        "first_name": "marc",
        "last_name": "benioff",
        "title": "ceo",
        "job_function": "",
        "management_level": "c_level",
        "gender": "male",
        "email": "mbenioff@salesforce.com",
        "email_status": "valid",
        "city": "San Francisco",
        "state": "CA",
        "country": "United States",
        "linkedin_url": "https://www.linkedin.com/in/marcbenioff/",
        "company": {
            "id": "c7d44d9a-b84a-459a-9003-75e10415f74a",
            "company_name": "Salesforce.com, Inc.",
            "domain": "salesforce.com",
            "address": "415 Mission Street, 3rd Floor",
            "city": "San Francisco",
            "state": "CA",
            "zip": 94105,
            "country": "United States",
            "county": "San Francisco",
            "phone_number": "4159017000",
            "fax_number": "4159017040",
            "employees": "Over 10,000",
            "revenue": "Over $1 Billion",
            "industry": "Internet",
            "sic_code": 7372,
            "sic_description": "Prepackaged Software",
            "naics_code": 518210,
            "naics_description": "Data Processing, Hosting, and Related Services",
            "description": "Salesforce.com, Inc. is an American cloud-based software 
company, headquartered in San Francisco, California. Though the bulk of its revenue 
comes from a customer relationship management (CRM) product, Salesforce also sells a 
complementary suite of enterprise applications focused on customer service, marketing 
automation, analytics and application development.",
            "year_founded": 1999,
            "logo": "https://logo.uplead.com/salesforce.com",
            "linkedin_url": "https://www.linkedin.com/company/salesforce",
            "twitter_url": "http://twitter.com/salesforce",
            "facebook_url": "https://www.facebook.com/salesforce",
            "youtube_url": "https://www.youtube.com/user/salesforce",
            "crunchbase_url": "https://www.crunchbase.com/organization/salesforce",
            "yelp_url": "https://www.yelp.com/biz/salesforce-san-francisco",
            "instagram_url": "https://instagram.com/salesforce/",
            "type": "Public",
            "ticker": "CRM",
            "exchange": "NYSE",
            "alexa_rank": 123
        } 
    }
}

Our Combined (Person + Company) API lets you lookup a person and company simultaneously based on an email address. The endpoint requires an email address and you get both the person and company information.

Example Request

GET

https://api.uplead.com/v2/combined-search?email=mbenioff@salesforce.com


POST

https://api.uplead.com/v2/combined-search

Request JSON body:

{ "email": "mbenioff@salesforce.com" }

Parameters

Parameter Description
email Required
email address (e.g – mbenioff@salesforce.com)
string

Attributes

Attribute Description
id string
internal person id
first_name string
person first name
last_name string
person last name
title string
person job title
job_function string
person job function
management_level string
person management level (M level, D level, VP level, C level)
gender string
person gender
email string
person email address
email_status string
person email address status code
city string
person city
state string
person state
country string
person country
linkedin_url string
person linkedin url
company object
company attributes

Company Attributes

Attribute Description
id string
internal company id
company_name string
name of the company
domain string
company website url
address string
hq address
city string
hq city name
state string
hq state name
zip string
hq zip code
country string
hq country name
county string
hq county name
phone_number string
company phone number
fax_number string
company fax number
employees string
employees range (1 - 10, 10 - 50, 50 - 200, 200 - 500, 500 - 1,000, 1,000 - 5,000, 5,000 - 10,000, Over 10,000)
revenue string
revenue range (0 - $1 Million, $1 Million - $10 Million, $10 Million - $50 Million, $50 Million - $100 Million, $100 Million - $200 Million, $200 Million - $1 Billion, Over $1 Billion)
industry string
company industry name
sic_code integer
company sic code
sic_description string
company sic code industry description
naics_code integer
company naics code
naics_description string
company naics code industry description
description string
company description
year_founded integer
company year founded
logo string
company logo url
linkedin_url string
company linkedin url
twitter_url string
company twitter url
facebook_url string
company facebook url
youtube_url string
company youtube url
crunchbase_url string
company crunchbase url
yelp_url string
company yelp url
instagram_url string
company instagram url
type string
company type (private, public, education, government, non-profit)
ticker string
company stock ticker
exchange string
company stock exchange
alexa_rank integer
company website alexa ranking

Prospector API

Response:

{
    "data": {
        "results": [
            {
                "id": "5f77c393-111f-4c57-9feb-cb777b02418d",
                "first_name": "mark",
                "last_name": "hawkins",
                "title": "president & cfo",
                "job_function": "finance",
                "management_level": "c_level",
                "gender": "male",
                "email": "mhawkins@salesforce.com",
                "email_status": "valid",
                "phone_number": "4159017000",
                "city": "San Francisco",
                "state": "CA",
                "country": "United States",
                "linkedin_url": "https://www.linkedin.com/in/markjhawkins/",
                "industry": "Internet",
                "domain": "salesforce.com",
                "company_name": "Salesforce.com, Inc."
            }
        ],
        "meta": {
            "total": 100,
            "page": 1,
            "next_page": 2,
            "previous_page": null,
            "first_page": true,
            "last_page": false
        }
    }
}

Our Prospector API lets you find contacts and emails associated with a company, job title, job function, management level and location.

Example Request

GET

https://api.uplead.com/v2/prospector-search?domain=salesforce.com&job_function=finance


POST

https://api.uplead.com/v2/prospector-search

Request JSON body:

{ "domain": "salesforce.com", "job_function": "finance" }

Parameters

Parameter Description
domain Required
domain URL of the company you want to search against. (e.g – amazon.com)
string
job_function Optional
person job function to filter by.
string
Allowed values:
  • Business Development
  • Community and Social Services
  • Consulting
  • Education
  • Engineering and Technical
  • Finance
  • Healthcare and Medical
  • Human Resources
  • Information Technology
  • Legal
  • Marketing
  • Media and Communications and PR
  • Operations
  • Program & Product Management
  • Purchasing and Buyers
  • Real Estate
  • Research
  • Sales
management_level Optional
person management level to filter by
string
Allowed values:
  • M level
  • D level
  • VP level
  • C level
title Optional
person job title to filter by.
string
titles Optional
multiple job titles to filter by.
array of strings
city Optional
city to filter by
string
cities Optional
multiple cities to filter by.
array of strings
state Optional
state to filter by.
string
states Optional
multiple states to filter by.
array of strings
country Optional
country to filter by
string
name Optional
name of person to filter by
string
exclusion_list_names Optional
list names that you want to apply for exclusion
You must upload your lists first here
array of strings
page Optional
which results page to show (default is 1).
integer
per_page Optional
number of results returned (default is 25, max is 100)
integer

Attributes

Attribute Description
id string
internal person id
first_name string
person first name
last_name string
person last name
title string
person job title
job_function string
person job function (Business Development, Community and Social Services, Consulting, Education, etc)
management_level string
person management level (M level, D level, VP level, C level)
gender string
person gender
email string
person email address
email_status string
person email address status code
phone_number string
company phone number
city string
person city
state string
person state
country string
person country
linkedin_url string
person linkedin url
industry string
company industry name
domain string
company domain url
company_name string
company name

Meta Attributes

Attribute Description
total integer
total number of records found
page integer
number of current page
next_page integer
number of next page to retrieve
previous_page integer
number of previous page to retrieve
first_page boolean
determine if current page is first
last_page boolean
determine if current page is last

Prospector Pro API

Response:

{
    "data": {
        "results": [
            {
                "id": "5f77c393-111f-4c57-9feb-cb777b02418d",
                "first_name": "mark",
                "last_name": "hawkins",
                "title": "president & cfo",
                "job_function": "finance",
                "management_level": "c_level",
                "gender": "male",
                "email": "mhawkins@salesforce.com",
                "email_status": "valid",
                "city": "San Francisco",
                "state": "CA",
                "country": "United States",
                "linkedin_url": "https://www.linkedin.com/in/markjhawkins/",
                "company": {
                    "id": "c7d44d9a-b84a-459a-9003-75e10415f74a",
                    "company_name": "Salesforce.com, Inc.",
                    "domain": "salesforce.com",
                    "address": "415 Mission Street, 3rd Floor",
                    "city": "San Francisco",
                    "state": "CA",
                    "zip": 94105,
                    "country": "United States",
                    "county": "San Francisco",
                    "phone_number": "4159017000",
                    "fax_number": "4159017040",
                    "employees": "Over 10,000",
                    "revenue": "Over $1 Billion",
                    "industry": "Internet",
                    "sic_code": 7372,
                    "sic_description": "Prepackaged Software",
                    "naics_code": 518210,
                    "naics_description": "Data Processing, Hosting, and Related Services",
                    "description": "Salesforce.com, Inc. is an American cloud-based software
company, headquartered in San Francisco, California. Though the bulk of its revenue 
comes from a customer relationship management (CRM) product, Salesforce also sells a 
complementary suite of enterprise applications focused on customer service, marketing 
automation, analytics and application development."
                    "year_founded": 1999,
                    "logo": "https://logo.uplead.com/salesforce.com",
                    "linkedin_url": "https://www.linkedin.com/company/salesforce",
                    "twitter_url": "http://twitter.com/salesforce",
                    "facebook_url": "https://www.facebook.com/salesforce",
                    "youtube_url": "https://www.youtube.com/user/salesforce",
                    "crunchbase_url": "https://www.crunchbase.com/organization/salesforce",
                    "yelp_url": "https://www.yelp.com/biz/salesforce-san-francisco",
                    "instagram_url": "https://instagram.com/salesforce/",
                    "type": "Public",
                    "ticker": "CRM",
                    "exchange": "NYSE",
                    "alexa_rank": 123
                }
            }
        ],
        "meta": {
            "total": 100,
            "page": 1,
            "next_page": 2,
            "previous_page": null,
            "first_page": true,
            "last_page": false
        }
    }
}

Our Prospector Pro API lets you find contacts and company details by searching in a similar manner to our web application including by job title, industry, location, and more. The Prospector Pro API is available on the Professional, Elite, and Enterprise plans only.

Example Request

GET

https://api.uplead.com/v2/prospector-pro-search?domain=salesforce.com&job_functions[]=finance


POST

https://api.uplead.com/v2/prospector-pro-search

Request JSON body:

{ "domain": "salesforce.com", "job_functions": ["finance"] }

Parameters

Parameter Description
domain Optional
domain URL of the company you want to search against. (e.g – amazon.com)
string
name Optional
name of person to filter by
string
job_functions Optional
multiple person job functions to filter by.
array of strings
Allowed values:
  • Business Development
  • Community and Social Services
  • Consulting
  • Education
  • Engineering and Technical
  • Finance
  • Healthcare and Medical
  • Human Resources
  • Information Technology
  • Legal
  • Marketing
  • Media and Communications and PR
  • Operations
  • Program & Product Management
  • Purchasing and Buyers
  • Real Estate
  • Research
  • Sales
management_levels Optional
multiple person management levels to filter by
array of strings
Allowed values:
  • M level
  • D level
  • VP level
  • C level
titles Optional
multiple job titles to filter by.
array of strings
title_search_mode Optional
search mode for titles (default is "exact")
string
Allowed values:
  • include
  • exact
cities Optional
multiple cities to filter by.
array of strings
states Optional
multiple states to filter by.
array of strings
countries Optional
multiple countries to filter by.
array of strings
regions Optional
multiple regions to filter by.
array of strings
Allowed values:
  • AMER
  • APAC
  • EMEA
  • LATAM
location_target Optional
entity for location search (default is "company")
string
Allowed values:
  • contact
  • company
business_types Optional
multiple business types to filter by.
array of strings
Allowed values:
  • education
  • government
  • non_profit
  • public
  • private
  • subsidiary
industries Optional
multiple industries to filter by.
array of strings
sic_codes Optional
multiple sic codes to filter by.
array of strings
naics_codes Optional
multiple naics codes to filter by.
array of strings
employees Optional
multiple employees codes to filter by.
array of strings
Allowed values:
  • 1 to 10
  • 10 to 50
  • 50 to 200
  • 200 to 500
  • 500 to 1,000
  • 1,000 to 5,000
  • 5,000 to 10,000
  • Over 10,000
revenues Optional
multiple revenues codes to filter by.
array of strings
Allowed values:
  • Under $1 Million
  • $1 Million - $10 Million
  • $10 Million - $50 Million
  • $50 Million - $100 Million
  • $100 Million - $200 Million
  • $200 Million - $1 Billion
  • Over $1 Billion
exclude_eu Optional
exclude EU contacts (default: "false")
boolean
exclusion_list_names Optional
list names that you want to apply for exclusion
You must upload your lists first here
array of strings
page Optional
which results page to show (default is 1).
integer
per_page Optional
number of results returned (default is 25, max is 100)
integer

Attributes

Attribute Description
id string
internal person id
first_name string
person first name
last_name string
person last name
title string
person job title
job_function string
person job function (Business Development, Community and Social Services, Consulting, Education, etc)
management_level string
person management level (M level, D level, VP level, C level)
gender string
person gender
email string
person email address
email_status string
person email address status code
phone_number string
company phone number
city string
person city
state string
person state
country string
person country
linkedin_url string
person linkedin url

Company Attributes

Attribute Description
id string
internal company id
company_name string
name of the company
domain string
company website url
address string
hq address
city string
hq city name
state string
hq state name
zip string
hq zip code
country string
hq country name
county string
hq county name
phone_number string
company phone number
fax_number string
company fax number
employees string
employees range (1 - 10, 10 - 50, 50 - 200, 200 - 500, 500 - 1,000, 1,000 - 5,000, 5,000 - 10,000, Over 10,000)
revenue string
revenue range (0 - $1 Million, $1 Million - $10 Million, $10 Million - $50 Million, $50 Million - $100 Million, $100 Million - $200 Million, $200 Million - $1 Billion, Over $1 Billion)
industry string
company industry name
sic_code integer
company sic code
sic_description string
company sic code industry description
naics_code integer
company naics code
naics_description string
company naics code industry description
description string
company description
year_founded integer
company year founded
logo string
company logo url
linkedin_url string
company linkedin url
twitter_url string
company twitter url
facebook_url string
company facebook url
youtube_url string
company youtube url
crunchbase_url string
company crunchbase url
yelp_url string
company yelp url
instagram_url string
company instagram url
type string
company type (private, public, education, government, non-profit)
ticker string
company stock ticker
exchange string
company stock exchange
alexa_rank integer
company website alexa ranking

Meta Attributes

Attribute Description
total integer
total number of records found
page integer
number of current page
next_page integer
number of next page to retrieve
previous_page integer
number of previous page to retrieve
first_page boolean
determine if current page is first
last_page boolean
determine if current page is last

Company Name to Domain API

Response:

{
    "data": {
        "company_name": "Amazon.com, Inc.",
        "domain": "amazon.com",
        "logo": "https://logo.uplead.com/amazon.com"
    }
}

Our Company Name to Domain API lets you convert the name of a company to its website domain and logo. The match is based on exact company name and returns the most important company (based on website traffic). Please note because not all company names are unique, there may be some inaccuracy in the results.

Example Request

GET

https://api.uplead.com/v2/company-name-to-domain?company_name=amazon


POST

https://api.uplead.com/v2/company-name-to-domain

Request JSON body:

{ "company_name": "amazon" }

Parameters

Parameter Description
company_name Required
the name of company
string

Attributes

Attribute Description
company_name string
name of the company
domain string
company website url
logo string
company logo url