For your growth team

Design your own sales machine by taking advantage of our APIs

city-bis Search our database of companies with thousands of filterscity Enrich a company from its domain name and get 50+ data pointshourglass Find all email formats used by a specific domain
Introduction
Authentication
Errors
Companies
Locations

API Reference

The ProspectWith API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right. We provide examples in Curl, Ruby, PHP, Java - and for Events, JavaScript.

Need help?

Message us in the chatbox. A developer will reply under 1 hour to see how we can solve your issue.

Not a developer?

We can help you integrate our API. Send us a message in the chatbox.

Base URL
https://api.prospectwith.com

Authentication

The ProspectWith API uses API token to authenticate requests. You can view and manage your API tokens in your settings.

Your API tokens carry many privileges , so be sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. Those authentication keys are permanent (they never expire). You can consider them safe for long-term purposes.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

There are two ways to authenticate your HTTP requests to the API:

  • By adding an Authorization header. The Authorization header is formatted as such: Authorization: Basic MY-API-TOKEN (replace MY-API-TOKEN with one of yours).

  • By sending the API token as a GET parameter: https://api.prospectwith.com/v1/companies/amazon.com?token=MY-API-TOKEN (mostly used for quick testing).

Your API tokens
Your API token is included in all the examples here, so you can test any example right away. Only you can see this value.

Errors

ProspectWith uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with ProspectWith's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a parameter is missing) include an error code that briefly explains the error reported.

Attributes

code string
For some errors that could be handled programmatically, a short string indicating the error code reported. 403
message string
A human-readable message providing more details about the error. For card errors, these messages can be shown to your users. Missing api token
param string
If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field. The Company domain is not a string
type enum
The type of error returned. apiConnectionError
Possible values apiConnectionError apiError authenticationError invalidRequestError rateLimitError restrictionError
HTTP status code summary
200 - OK 500, 502, 503, 504 - Server Errors
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API token provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API token doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on ProspectWith's end. (These are rare.)
HTTP status code summary
apiConnectionError Failure to connect to ProspectWith's API.
apiError API errors cover any other type of problem (e.g., a temporary problem with ProspectWith's servers), and are extremely uncommon.
authenticationError Failure to properly authenticate yourself in the request.
invalidRequestError Invalid request errors arise when your request has invalid parameters.
rateLimitError Too many requests hit the API too quickly.
restrictionError Retrictions have been reached. Please contact us.

Companies

An important thing to remember is that on ProspectWith, a company object is represented by a domain (e.g. amazon.com). This means that when we discover a new domain, we will consider it as a new company.

For the time being, the API only allows you to retrieve companies. If you need additional endpoints, feel free to reach us in the chatbox.

Available Endpoints
GET /v1/companies
GET /v1/companies/:domain

Fetch a company

Retrieves the details of an existing company (revenue, total employees, social networks, technologies…). The company's domain or company's name must be provided in the query for a result to be returned.

Query parameters

domain required
The company domain. …/companies/amazon.com

Response

Returns a company object with all the information. When no company matches the provided domain, a 404 responses will be returned. Make sure to handle this case in your code.

Response attributes

alexaRank number
The company's Alexa rank. 8
analyzedAt string
The last time the company has been analyzed. 2021-12-22T15:49:15.000Z
businessType string
The company's business type. public-company
Possible values educational-institution government-agency nonprofit partnership privately-held public-company self-employed sole-proprietorship
city object
The company's city.
Show child attributes
codeNaics string
The company's code NAICS. 518210
codeSic string
The company's code SIC. 5961
country object
The company's country.
Show child attributes
description string
The company's description. Amazon.com, Inc. is an American multinational technology company based in Seattle, Washington, which focuses on…
domain string
The company's domain. amazon.com
domainName string
The company's domain name. amazon
domainTld string
The company's top level domain. com
industries array
The company's industries. Internet, Fashion, Marketing…
logo string
The company's logo url. https://spaces.prospectwith.com/images/companies/a2a8283864386ca04a5694e8b58759e6.jpg
monthlyVisitors enum
The company's total monthly visitors. over-1b
Possible values under-10k 10k-50k 50k-100k 100k-500k 500k-1m 1m-10m 10m-50m 50m-100m 100m-500m 500m-1b over-1b
name string
The company's name. Amazon
phoneNumber string
The company's phone number. 00 1 206-922-0880
prospectwithUrl string
The company's ProspectWith url. https://www.prospectwith.com/companies/amazon.com
revenue enum
The company's revenue. over-1b
Possible values under-1m 1m-10m 10m-50m 50m-100m 100m-200m 200m-1b over-1b
socialNetworks object
The company's social networks.
Show child attributes
technologies array
The company's technologies.
technologyCategories array
The company's categories of technologies.
totalEmployees enum
The company's total number of employees. over-10k
Possible values 1-10 10-50 50-200 200-500 500-1k 1k-5k 5k-10k over-10k
yearFounded number
The company's year of foundation. 1994
websiteUrl string
The company's website url. https://www.amazon.com
Endpoint
GET /v1/companies/amazon.com
Response 
{
  "alexaRank": 8,
  "analyzedAt": "2021-12-22T15:49:15.000Z",
  "businessType": "public-company",
  "city": {
    "address": "410 Terry Ave N",
    "code": "seattle|washington|us",
    "county": "King County",
    "latitude": "47.6038321",
    "longitude": "-122.3300624",
    "name": "Seattle",
    "state": "Washington",
    "postcode": "98101"
  },
  "codeNaics": "518210",
  "codeSic": "5961",
  "country": {
    "name": "United States of America",
    "code": "us",
    "continent": "North America",
    "continentCode": "na",
    "latitude": "39.7837304",
    "longitude": "-100.4458825"
  },
  "description": "Free delivery on millions of items with Prime. Low prices across earth's biggest selection of books, music, DVDs, electronics, computers, software, apparel & accessories, shoes, jewelry, tools & hardware, housewares, furniture, sporting goods, beauty & personal care, groceries & just about anything else.",
  "domain": "amazon.com",
  "domainName": "amazon",
  "domainTld": "com",
  "industries": ["internet", "ecommerce", "retail", "operations"],
  "logo": "https://spaces.prospectwith.com/images/companies/a2a8283864386ca04a5694e8b58759e6.jpg",
  "monthlyVisitors": "over-1b",
  "name": "Amazon",
  "phoneNumber": "00 1 206-922-0880",
  "prospectwithUrl": "https://www.prospectwith.com/companies/amazon.com",
  "revenue": "over-1b",
  "socialNetworks": {
    "angellist":  "https://angel.co/amazon",
    "facebook": "https://www.facebook.com/Amazon",
    "instagram": "https://www.instagram.com/amazon",
    "linkedin": "https://www.linkedin.com/company/amazon",
    "twitter": "https://twitter.com/amazon"
  },
  "technologies": ["amazon-cloudfront", "amazon-s3", ...],
  "technologyCategories": ["cdn", ...],
  "totalEmployees": "over-10k",
  "websiteUrl": "https://www.amazon.com",
  "yearFounded": 1994
}

Find email patterns

Retrieve all email patterns used by a given company. We use this endpoint internally to prioritize the patterns when we want to find a business email address.

Query parameters

domain required
The company domain. …/companies/amazon.com/email-patterns

Read the pattern attributes

[F] string
The first name leonardo for Leonardo DiCaprio
[F1] string
The first letter of the first name l for Leonardo DiCaprio
[L] string
The last name dicaprio for Leonardo DiCaprio
[L1] string
The first letter of the last name d for Leonardo DiCaprio
[M] string
The middle name fitzgerald for John Fitzgerald Kennedy
[M1] string
The first letter of the middle name f for John Fitzgerald Kennedy

Response

Returns an array including all the email patterns and their usage. When no company matches the provided domain, an empty array will be returned. Make sure to handle this case in your code.

Response attributes

pattern string
The email pattern used [F1][L]
usagePercentage number
The number of times this pattern has been used in percentage 82.6087
Endpoint
GET /v1/companies/amazon.com/email-patterns
Response 
[
  {
    "pattern": "[F]",
    "usagePercentage": 82.6087
  },
  {
    "pattern": "[F1][L]",
    "usagePercentage": 8.6957
  },
  {
    "pattern": "[F].[L]",
    "usagePercentage": 8.6957
  }
]

Locations

The following endpoints will let you search and browse all available locations on ProspectWith: cities, counties, states, and countries.

You can use these endpoints to display a list of locations on your website to filter your results while fetching companies.

Available Endpoints
GET /v1/locations/cities
GET /v1/locations/counties
GET /v1/locations/states
GET /v1/locations/countries

Search cities

Query parameters

page optional
The page to fetch (default to 1). …/locations/cities?page=1
search optional
An additionnal search query applied to the city name. …/locations/cities?search=new%20york
size optional
The number of cities to be returned (between 1 and 50). Default to 10. …/locations/cities?size=50

Response

Returns a paginated response including the cities that match with your search. When no results can be found, the data property will be an empty array.

Attributes

data array
The cities that match your conditions.
Show child attributes
metas array
The metas information.
Show child attributes
Endpoint
GET /v1/locations/cities
Response 
{
  data: [
    {
      "code": "new_york|new_york|us",
      "companiesCount": 37691,
      "country": {
        "citiesCount": 20995,
        "code": "us",
        "companiesCount": 1050972,
        "continent": "North America",
        "continentCode": "na",
        "id": 233,
        "latitude": "39.7837304",
        "longitude": "-100.4458825",
        "name": "United States",
        "usageCount": 302
      },
      "county": null,
      "id": 55,
      "latitude": "40.7127281",
      "longitude": "-74.0060152",
      "name": "New York",
      "postcode": null,
      "state": "New York",
      "usageCount": 7,
    }
    // …
  ],
  metas: {
    firstPage: 1,
    firstPageUrl: `?page=1`,
    lastPage: 10,
    lastPageUrl: `?page=10`,
    nextPageUrl: 2,
    perPage: 50,
    previousPageUrl: null,
    total: 500,
  }
}

Search counties

Query parameters

page optional
The page to fetch (default to 1). …/locations/counties?page=1
search optional
An additionnal search query applied to the county name. …/locations/counties?search=newport
size optional
The number of counties to be returned (between 1 and 50). Default to 10. …/locations/counties?size=50

Response

Returns a paginated response including the counties that match with your search. When no results can be found, the data property will be an empty array.

Attributes

data array
The counties that match your conditions.
Show child attributes
metas array
The metas information.
Show child attributes
Endpoint
GET /v1/locations/counties
Response 
{
  data: [
    {
      "country": {
        "citiesCount": 796,
        "code": "in",
        "companiesCount": 81653,
        "continent": "Asia",
        "continentCode": "as",
        "id": 105,
        "latitude": "22.3511148",
        "longitude": "78.6677428",
        "name": "India",
        "usageCount": 133
      },
      "name": "Bangalore North",
    },
    // …
  ],
  metas: {
    firstPage: 1,
    firstPageUrl: `?page=1`,
    lastPage: 10,
    lastPageUrl: `?page=10`,
    nextPageUrl: 2,
    perPage: 50,
    previousPageUrl: null,
    total: 500,
  }
}

Search states

Query parameters

page optional
The page to fetch (default to 1). …/locations/states?page=1
search optional
An additionnal search query applied to the state name. …/locations/states?search=new%20york
size optional
The number of states to be returned (between 1 and 50). Default to 10. …/locations/states?size=50

Response

Returns a paginated response including the states that match with your search. When no results can be found, the data property will be an empty array.

Attributes

data array
The states that match your conditions.
Show child attributes
metas array
The metas information.
Show child attributes
Endpoint
GET /v1/locations/states
Response 
{
  data: [
    {
      "name": "Distrito Nacional",
      "country": {
        "citiesCount": 25,
        "code": "do",
        "companiesCount": 1047,
        "continent": "North America",
        "continentCode": "na",
        "id": 61,
        "latitude": "19.0974031",
        "longitude": "-70.3028026",
        "name": "Dominican Republic",
        "usageCount": 0
      }
    },
    // …
  ],
  metas: {
    firstPage: 1,
    firstPageUrl: `?page=1`,
    lastPage: 10,
    lastPageUrl: `?page=10`,
    nextPageUrl: 2,
    perPage: 50,
    previousPageUrl: null,
    total: 500,
  }
}

Search countries

Query parameters

page optional
The page to fetch (default to 1). …/locations/countries?page=1
search optional
An additionnal search query applied to the country name. …/locations/countries?search=france
size optional
The number of countries to be returned (between 1 and 50). Default to 10. …/locations/countries?size=50

Response

Returns a paginated response including the countries that match with your search. When no results can be found, the data property will be an empty array.

Attributes

data array
The countries that match your conditions.
Show child attributes
metas array
The metas information.
Show child attributes
Endpoint
GET /v1/locations/countries
Response 
{
  data: [
    {
      "citiesCount": 20995,
      "code": "us",
      "companiesCount": 1050972,
      "continent": "North America",
      "continentCode": "na",
      "id": 233,
      "latitude": "39.7837304",
      "longitude": "-100.4458825",
      "name": "United States",
      "usageCount": 302
    },
    // …
  ],
  metas: {
    firstPage: 1,
    firstPageUrl: `?page=1`,
    lastPage: 10,
    lastPageUrl: `?page=10`,
    nextPageUrl: 2,
    perPage: 50,
    previousPageUrl: null,
    total: 500,
  }
}