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

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_validation_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": "51422990-fb53-4ce0-9e6d-efc9a1c9c606",
        "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/POST https://api.uplead.com/v2/company-search?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 integer
company phone number
fax_number integer
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": "2993a850-ca8a-45e3-b329-c63377f36876",
        "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/POST https://api.uplead.com/v2/person-search?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": "2993a850-ca8a-45e3-b329-c63377f36876",
        "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": "51422990-fb53-4ce0-9e6d-efc9a1c9c606",
            "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/POST https://api.uplead.com/v2/combined-search?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 integer
company phone number
fax_number integer
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/POST https://api.uplead.com/v2/prospector-search?domain=salesforce.com&job_function=finance

Parameters

Parameter Description
domain Required
domain URL of the company you want to search against.
string
job_function Optional
person job function to filter by.
string
management_level Optional
person management level to filter by
string
title Optional
person job title to filter by.
string
titles[] Optional
multiple job titles to filter by. You can specify this param multiple times to search for multiple titles
array of string
city Optional
city to filter by
string
cities[] Optional
multiple cities to filter by. You can specify this param multiple times to search for multiple cities.
array of string
state Optional
state to filter by.
string
states[] Optional
multiple states to filter by. You can specify this param multiple times to search for multiple states.
array of string
country Optional
country to filter by
string
name Optional
name of person to filter by
string
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

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/POST https://api.uplead.com/v2/company-name-to-domain?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