API Reference

Welcome to Corpping’s API! You can use this API to access all our API endpoints, such as the CompanyConnect API to look up email addresses, or the Company API to look up company information related to a domain name.

The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

We also have some specific language bindings to make integration easier. You can switch the programming language of the examples with the tabs in the top right.

Currently we support the following official client bindings:

Authentication

Authentication using HTTP basic auth.
curl 'https://person.corpping.com/v1/people/email/martin@corpping.com' \
        -u {key}:
Alternatively pass a Bearer token in an Authorization header.
curl 'https://person.corpping.com/v1/people/email/martin@corpping.com' \
        -H 'Authorization: Bearer {key}'

Authentication is done via the API key which you can find in your account settings.

Requests are authenticated using HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

Alternatively you can also pass your API key as a bearer token in an Authorization header.

You can see your account’s API keys, and roll them if necessary, in the dashboard.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

HTTP Status codes

Code Title Description
200 OK The request was successful.
201 Created The resource was successfully created.
202 Async created The resource was asynchronously created
400 Bad request Bad request
422 Validation error A validation error occurred.
401 Unauthorized Your API key is invalid.
404 Not found The resource does not exist.
50X Internal Server Error An error occurred with our API.

Error types

All errors are returned in the form of JSON with a type and optional message.

Example error response.

  {
    "error": {
      "type": "params_invalid",
      "message": "Name is required"
    }
  }
Type Description
params_invalid Your parameters were not valid.
unknown_record Record was not found.
unknown_route URL was not valid.
queued Lookup queued. Try this request again in a few minutes.
rate_limit The request has been rate limited.
api_error Internal API error.

Rate limiting

Check to see how many requests we have left:

$ curl -i https://person.corpping.comm

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2014 21:20:00 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4050
X-RateLimit-Reset: 3300

You can make 600 requests per minute to each API, unless you are using Streaming. Check the returned HTTP headers of any API request to see your current rate limit status. If you’re running into this error or think you’ll need a higher rate limit, drop us a line at support@corpping.comm. The Streaming version of each API is limited to 5 concurrent connections rather than being limited by the number of requests per minute.

Example rate limit error response.

HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1402010983
Content-Type: application/json
  {
    "error": {
      "type": "rate_limit",
      "message": "Rate limit exceeded. Limit is 600 requests per minute. Rate limit will be reset in 50 seconds."
    }
  }
Header Name
X-RateLimit-Limit The maximum number of requests that the consumer 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.

Once you go over the rate limit you will receive a rate_limit error response.

Versioning

You can pass a specific API version like so:

curl 'https://person.corpping.com/v1/people/email/martin@corpping.com' \
        -H 'API-Version: 2016-08-31' \
        -u {key}:

When we make backwards-incompatible changes to any of our APIs, we release new dated versions. Each API we provide has a separate version (listed below).

All requests will use your account API settings, unless you override the API version by sending a API-Version header identifying the API version to use. (For libraries and bindings, this is done by setting an API version property as in the code examples.)

Any webhooks triggered will also use a request specified version before falling back to your account’s version.

You can visit your dashboard to upgrade your API version. You can also see a full API version changelog here.

API Current Version
CompanyConnect API 2016-08-31
Company API 2016-05-18

Webhooks

The incoming webhook POST request’s body is formatted as JSON, and looks like this:

{
  "id": "custom_id",
  "status": 200,
  "body": {
    "name": {
      "givenName": "Martin",
      "familyName": "Beiber",
      "fullName": "Martin Beiber"
    },
    "//": "..."
  }
}

Certain requests, such as looking up an email address, may have an asynchronous response (since there’s some complex background processing involved). For these requests you can either poll the endpoint, or give us a webhook URL you want to be called when the request has finished processing.

You can set a webhook URL endpoint in your account settings to be used with all requests.

To link up your requests to webhooks you can pass a webhook_id parameter when making these calls, containing a custom defined webhook identifier. We’ll pass this identifier back to you with the webhook request.

If you return anything other than a HTTP 200 status to the webhook POST then we’ll try to deliver the webhook up to 5 times with an exponential backoff.

Response POST body

Attribute Description
id string Custom user-supplied webhook identifier.
type string Either person, company, person_company, or candidate_match.
status integer Either a 200 status code (record was found), or a 404 status code (record was not found).
body hash Result object, either null or the encoded person.

For testing webhooks, we recommend a useful service called requestb.in, which allows you to inspect arbitrary webhook requests.

Securing webhooks

To validate a webhook came from Corpping we suggest verifying the webhook payloads with the X-Request-Signature header (which we pass with every webhook). If you’re using one of our client bindings to parse webhooks, say the Ruby library, we’ll do this for you.

Header Name
X-Request-Signature A SHA1 HMAC hexdigest computed with your API key and the raw body of the request. Make sure to strip the prefix (sk_, pk_) from the start of the key before generating the HMAC.

Streaming

To look up a person:

curl 'https://person-stream.corpping.com/v1/people/email/martin@corpping.com' \
        -u {key}:

Or to look up a company:

curl 'https://company-stream.corpping.com/v1/companies/domain/stripe.com' \
        -u {key}:

An alternative to using webhooks is our streaming API. This API is ideal if you don’t mind long lived requests (e.g. you’re making requests to Corpping from a messaging queue).

When we need to do an asynchronous lookup, say when looking up a person by email address, rather than requiring you to poll the endpoint the streaming API will simply keep the connection open until we have some data.

Requests made to the streaming API will never return a HTTP 202 status response, and can be held open for up to a minute.

The only difference between making calls to the normal and streaming API is the subdomain - person-stream.corpping.comm rather than person.corpping.comm.

CompanyConnect API

The CompanyConnect API lets you look up person and company data based on an email or domain. For example, you could retrieve a person’s name, location and social handles from an email. Or you could lookup a company’s location, headcount or logo based on their domain name.

Note: You’ll only be charged once per 30 day period for each unique request, so if you didn’t store the data properly or need to re-run a series of requests for any reason, those won’t count against your allotment.

Combined API

To lookup both a company and person based on an email address:

curl 'https://person-stream.corpping.com/v2/combined/find?email=martin@corpping.com' \
        -u {key}:

The stream option ensures that the request blocks until Corpping has found some data on both the person & company. For cached information this will return in the region of 300 milliseconds, for uncached requests 2-4 seconds. If speed is key, you can omit the stream option and try the request again later (if you receive a pending response). Alternatively you can use our webhook API.

curl 'https://person.corpping.com/v2/combined/find?email=martin@corpping.com' \
        -u {key}:

A common use-case is looking up a person and company simultaneously based on a email address. To save you making two requests to do this, we offer a combined lookup API.

This endpoint expects an email address, and will return an object containing both the person and company (if found). A call to the combined lookup will only count as one API call.

The API response object looks like the following. Note that either the ‘person’ or ‘company’ attribute can be nil if not found. For a full look at the attributes returned, see either the Person or Company attribute sections.

{
  "person": {
    "id": "d54c54ad-40be-4305-8a34-0ab44710b90d",
    "name": {
      "fullName": "Martin Beiber",
      "givenName": "Martin",
      "familyName": "Beiber"
    },
    "email": "martin@corpping.com",
    "//": "..."
  },
  "company": {
    "id": "c5a6a9c5-303a-455a-935c-9dffcd2ed756",
    "name": "Martin Beiber",
    "legalName": "Martin Beiber",
    "domain": "corpping.com",
    "//": "..."
  }
}

HTTP Request

GET https://person.corpping.com/v2/combined/find?email=:email

(Where :email is the person’s email address)

HTTP GET params

Alongside the email address you may also provide any additional attributes you have about the person, such as their given and family names. Including more detail will help us be more accurate when searching.

The supported parameters are:

param Description
email string (required) The email address to look up.
given_name string First name of person.
family_name string Last name of person. If you have this, passing this is strongly recommended.
ip_address string IP address of the person. If you have this, passing this is strongly recommended.
location string The city or country where the person resides.
company string The name of the person’s employer.
company_domain string The domain for the person’s employer.
linkedin string The LinkedIn URL for the person.
twitter string The Twitter handle for the person.
facebook string The Facebook URL for the person.
webhook_id string Custom identifier for the webhook request.
subscribe boolean Set to true to subscribe to the changes to the person.

Response Types

Code Description
200 Successful lookup, person & company encoded in the response body.
202 Asynchronously looking up the person & company.
404 Neither the Person or the Company were found.

CompanyConnect API

The CompanyConnect API lets you retrieve social information associated with an email address, such as a person’s name, location and Twitter handle.

Attributes

The dot notation indicates that the property is one level deep inside a hash. No attributes are guaranteed to be present, and if we can’t find data on a specific network, then we’ll return a null value for that attribute.

The JSON encoded response looks like this.

{
  "id": "d54c54ad-40be-4305-8a34-0ab44710b90d",
  "name": {
    "fullName": "Martin Beiber",
    "givenName": "Martin",
    "familyName": "Beiber"
  },
  "email": "martin@corpping.com",
  "gender": "male",
  "location": "San Francisco, CA, US",
  "timeZone": "America/Los_Angeles",
  "utcOffset": -8,
  "geo": {
    "city": "San Francisco",
    "state": "California",
    "stateCode": "CA",
    "country": "United States",
    "countryCode": "US",
    "lat": 37.7749295,
    "lng": -122.4194155
  },
  "bio": "O'Reilly author, software engineer & traveller. Founder of http://corpping.com",
  "site": "http://corpping.com",
  "avatar": "https://d1ts43dypk8bqh.cloudfront.net/v1/avatars/d54c54ad-40be-4305-8a34-0ab44710b90d",
  "employment": {
    "domain": "corpping.comm",
    "name": "Corpping",
    "title": "Founder and CEO",
    "role": "ceo",
    "seniority": "executive"
  },
  "facebook": {
    "handle": "mbeiber"
  },
  "github": {
    "handle": "martinb",
    "avatar": "https://avatars.githubusercontent.com/u/2142?v=2",
    "company": "Corpping",
    "blog": "http://corpping.com",
    "followers": 2932,
    "following": 94
  },
  "twitter": {
    "handle": "beiber",
    "id": "2006261",
    "bio": "O'Reilly author, software engineer & traveller. Founder of http://corpping.com",
    "followers": 15248,
    "following": 1711,
    "location": "San Francisco",
    "site": "http://corpping.com",
    "avatar": "https://pbs.twimg.com/profile_images/1826201101/297606_10150904890650705_570400704_21211347_1883468370_n.jpeg"
  },
  "linkedin": {
    "handle": "pub/martin-beiber/78/929/ab5"
  },
  "googleplus": {
    "handle": null
  },
  "angellist": {
    "handle": "beiber",
    "bio": "O'Reilly author, engineer & traveller. Mostly harmless.",
    "blog": "http://blog.corpping.com",
    "site": "http://corpping.com",
    "followers": 532,
    "avatar": "https://d1qb2nb5cznatu.cloudfront.net/users/403357-medium_jpg?1405661263"
  },
  "aboutme": {
    "handle": "beiber",
    "bio": "Software engineer & traveller. Walker, skier, reader, tennis player, breather, ginger beer drinker, scooterer & generally enjoying things :)",
    "avatar": "http://o.aolcdn.com/dims-global/dims/ABOUTME/5/803/408/80/http://d3mod6n032mdiz.cloudfront.net/thumb2/m/a/c/beiber/beiber-840x560.jpg"
  },
  "gravatar": {
    "handle": "martinb",
    "urls": [
      {
        "value": "http://corpping.com",
        "title": "Personal Website"
      }
    ],
    "avatar": "http://2.gravatar.com/avatar/994909da96d3afaf4daaf54973914b64",
    "avatars": [
      {
        "url": "http://2.gravatar.com/avatar/994909da96d3afaf4daaf54973914b64",
        "type": "thumbnail"
      }
    ]
  },
  "fuzzy": false,
  "emailProvider": false,
  "indexedAt": "2016-11-07T00:00:00.000Z"
}
Attribute Description
id string Internal ID
name.givenName string First name of person (if found)
name.familyName string Last name of person (if found)
name.fullName string Full formatted name of person. Sometimes this will be present even if the givenName or familyName aren’t available
gender string male or female
location string The most accurate location we have
timeZone string The timezone for the person’s location
utcOffset integer The offset from UTC in hours in the person’s location
geo.city string Normalized city based on location
geo.state string Normalized state based on location
geo.country string Normalized two letter country code based on location
geo.lat float General latitude based on location
geo.lng float General longitude based on location
bio string The most accurate bio we have
site string The person’s website
avatar string The best avatar url we have
employment.name string Company name
employment.title string Title at Company
employment.role string Role at Company
employment.seniority string Seniority at Company
employment.domain string Company domain
facebook.handle string Facebook ID or screen name
github.handle string GitHub handle
github.id integer GitHub ID
github.avatar string GitHub avatar
github.company string GitHub company
github.blog string GitHub blog url
github.followers string Count of GitHub followers
github.following string Count of GitHub following
twitter.handle string Twitter screen name
twitter.id integer Twitter ID
twitter.followers integer Count of Twitter followers
twitter.following integer Count of Twitter friends
twitter.location string Twitter location
twitter.site string Twitter site
twitter.statuses integer Tweet count
twitter.favorites integer Favorite count
twitter.avatar string HTTP Twitter avatar
linkedin.handle string LinkedIn url (i.e. /pub/martin-beiber/78/929/ab5)
googleplus.handle string Google Plus handle
angellist.handle string AngelList handle
angellist.id integer AngelList id
angellist.bio string AngelList bio
angellist.blog string AngelList blog
angellist.site string AngelList site
angellist.followers integer AngelList followers count
angellist.avatar string AngelList avatar url
aboutme.handle string about.me handle
aboutme.bio string about.me bio
aboutme.avatar string about.me avatar URL
gravatar.handle string Gravatar handle
gravatar.urls array Array of URLs from Gravatar
gravatar.avatar string Gravatar main avatar url.
gravatar.avatars string Array of objects containing a avatar url, and a type (i.e. thumbnail)
fuzzy boolean Indicating whether or not the lookup is a fuzzy or exact search
emailProvider boolean is the email domain associated with a free email provider (i.e. Gmail)?
indexedAt string date The time at which we indexed this data

Email lookup

The CompanyConnect API allows you to look up a person by their email address. Alongside the email address you may also provide any additional attributes you have about the person, such as their given and family names. Including more detail will help us be more accurate when searching.

The supported parameters are:

param Description
email string (required) The email address to look up.
given_name string First name of person.
family_name string Last name of person. If you have this, passing this is strongly recommended.
ip_address string IP address of the person. If you have this, passing this is strongly recommended.
location string The city or country where the person resides.
company string The name of the person’s employer.
company_domain string The domain for the person’s employer.
linkedin string The LinkedIn URL for the person.
twitter string The Twitter handle for the person.
facebook string The Facebook URL for the person.
To look up a person by email address, run the following. The command will either return a 404 (in which case the person wasn’t found), a 202 indicating the lookup has been queued, or a JSON object containing the relevant person.
curl 'https://person.corpping.com/v2/people/find?email=martin@corpping.com&company=Corpping' \
        -u {key}:

If you’d rather the request blocked until we find something (up to 60 seconds for uncached emails, but usually in the order of 10 seconds), then you can use our streaming API:

curl 'https://person-stream.corpping.com/v2/people/find?email=martin@corpping.com' \
        -u {key}:

This endpoint retrieves a person by email address. If we can find the person we’ll return a 200 status containing the record’s attributes.

Sometimes we’ll need to asynchronously lookup the person, in which case we’ll return an empty 202 status. Either try the same request again in a few minutes to get the full response, or register a webhook to be notified when we’ve finished searching for an email.

If we can’t find any information associated with the email address, we’ll return a 404 status.

HTTP Request

GET https://person.corpping.com/v2/people/find?email=:email

(Where :email is the person’s email address)

HTTP GET params

You can also pass the following optional parameters along when looking up people.

param Description
webhook_id string Custom identifier for the webhook request.
subscribe boolean Set to true to subscribe to the changes.

Response Types

Code Description
200 Successful lookup, person encoded in the response body.
202 Asynchronously looking up the person.
404 Person not found.

Subscribe

Subscribe to a person’s updates by passing the ‘subscribe’ parameter.

curl 'https://person.corpping.com/v2/people/find?email=martin@corpping.com&subscribe=true' \
        -u {key}:

You can subscribe to changes in people’s information by passing a subscribe parameter when looking up people. Whenever we receive updates, we’ll post them to the webhook url associated with your account. This will count as an API call.

You can set the webhook url associated with your account in your account’s settings.

Flagging

To flag a person’s data as incorrect

curl 'https://person.corpping.com/v1/people/d54c54ad-40be-4305-8a34-0ab44710b90d/flag' \
        -XPOST \
        -d 'given_name=Alexander' \
        -d 'employment_title=The Great' \
        -u {key}:

While we do our best to always return accurate data, we’re only lizards human and sometimes we make mistakes. This is especially true when the lookup is a fuzzy match rather than an exact one.

This endpoint allows you to let us know if a person doesn’t seem quite right. You can flag a person as incorrect and also optionally pass through a correct set of attributes.

We look into all the flagging we receive and incorporate fixes into future results.

HTTP Request

POST https://person.corpping.com/v1/people/:id/flag

Where :id is the id of the person you’d like to flag as inaccurate.

HTTP POST params

You can also optionally pass to us corrected versions of any of the person’s attributes we sent you.

param Description
given_name string (optional) First name of person
family_name string (optional) Last name of person
employment_title string (optional) Company title
facebook_handle string (optional) Facebook ID or screen name
github_handle string (optional) GitHub handle
twitter_handle string (optional) Twitter screen name
linkedin_handle string (optional) LinkedIn url (i.e. /pub/martin-beiber/78/929/ab5)
googleplus_handle string (optional) Google Plus handle.
angellist_handle string (optional) AngelList handle.
aboutme_handle string (optional) about.me handle

Response types

Code Description
200 Successful received, we will look into the issue.
404 Person not found.

Company API

Our Company API lets you lookup company data via a domain name.

Attributes

The JSON encoded response looks like:

{
  "id": "3f5d6a4e-c284-4f78-bfdf-7669b45af907",
  "name": "Uber",
  "legalName": "Uber Technologies, Inc.",
  "domain": "uber.com",
  "domainAliases": [
    "uber.org",
    "ubercab.com"
  ],
  "url": "https://www.uber.com",
  "site": {
    "url": "http://uber.com",
    "title": "Uber",
    "h1": "Your Ride, On Demand",
    "metaDescription": "Get a taxi, private car or rideshare from your mobile phone. Uber connects you with a driver in minutes. Use our app in cities around the world.",
    "metaAuthor": null,
    "phoneNumbers": [],
    "emailAddresses": [
      "domains@uber.com"
    ]
  },
  "category": {
    "sector": "Information Technology",
    "industryGroup": "Software & Services",
    "industry": "Internet Software & Services",
    "subIndustry": "Internet Software & Services"
  },
  "tags": [
    "Technology",
    "Marketplace",
    "Mobile",
    "B2C",
    "Ground Transportation",
    "Transportation",
    "Internet"
  ],
  "description": "Get a taxi, private car or rideshare from your mobile phone. Uber connects you with a driver in minutes. Use our app in cities around the world.",
  "foundedYear": 2009,
  "location": "1455 Market St, San Francisco, CA 94103, USA",
  "timeZone": "America/Los_Angeles",
  "utcOffset": -7,
  "geo": {
    "streetNumber": "1455",
    "streetName": "Market Street",
    "subPremise": null,
    "city": "San Francisco",
    "postalCode": "94103",
    "state": "California",
    "stateCode": "CA",
    "country": "United States",
    "countryCode": "US",
    "lat": 37.7752315,
    "lng": -122.4175278
  },
  "logo": "https://logo.corpping.com/uber.com",
  "facebook": {
    "handle": "uber"
  },
  "linkedin": {
    "handle": "company/uber-com"
  },
  "twitter": {
    "handle": "Uber",
    "id": "19103481",
    "bio": "Evolving the way the world moves by seamlessly connecting riders to drivers through our app. Question, concern, or praise? Tweet at @Uber_Support.",
    "followers": 570351,
    "following": 377,
    "location": "Global",
    "site": "http://t.co/11eIV5LX3Z",
    "avatar": "https://pbs.twimg.com/profile_images/697242369154940928/p9jxYqy5_normal.png"
  },
  "crunchbase": {
    "handle": "organization/uber"
  },
  "emailProvider": false,
  "type": "private",
  "ticker": null,
  "phone": null,
  "indexedAt": "2016-11-07T00:00:00.000Z",
  "metrics": {
    "alexaUsRank": 544,
    "alexaGlobalRank": 943,
    "employees": 20313,
    "employeesRange": "1000+",
    "marketCap": null,
    "raised": 10610000000,
    "annualRevenue": null
  },
  "tech": [
    "google_analytics",
    "double_click",
    "mixpanel",
    "optimizely",
    "typekit_by_adobe",
    "android",
    "nginx",
    "ios",
    "mixpanel",
    "google_apps"
  ]
}

A company object looks as follows. The dot notation indicates that the property is one level deep inside a hash. No attributes are guaranteed to be present, and if we can’t find data on a specific network (say Twitter), then we’ll return a null value for that attribute.

Attribute Description
id string Internal ID
name string Name of company
legalName string Legal name of company
domain string Domain of company’s website
domainAliases array List of domains also used by the company
site.url string URL of company’s website
site.title string HTML title contents of company’s website
site.phoneNumbers array List of phone numbers mentioned on the company’s website
site.emailAddresses array List of email addresses mentioned on the company’s website
tags array List of market categories (see a complete list)
category.sector string Broad sector (see a complete list)
category.industryGroup string Industry group (see a complete list)
category.industry string Industry (see a complete list)
category.subIndustry string Sub industry (see a complete list)
description string Description of the company
foundedYear integer Year company was founded
location string Address of company
timeZone string The timezone for the company’s location
utcOffset integer The offset from UTC in hours in the company’s location
geo.streetNumber string Headquarters street number
geo.streetName string Headquarters street name
geo.subPremise string Headquarters suite number
geo.city string Headquarters city name
geo.state string Headquarters state name
geo.stateCode string Headquarters two character state code
geo.postalCode string Headquarters postal/zip code
geo.country string Headquarters country name
geo.countryCode string Headquarters two character country code
geo.lat float Headquarters latitude
geo.lng float Headquarters longitude
metrics.raised integer Total amount raised
metrics.alexaUsRank integer Alexa’s US site rank
metrics.alexaGlobalRank integer Alexa’s global site rank
metrics.employees integer Amount of employees
metrics.marketCap integer Market Cap
metrics.annualRevenue integer Annual Revenue (public companies only)
facebook.handle string Company’s Facebook ID
linkedin.handle string Company’s Linkedin URL
twitter.handle string Twitter screen name
twitter.id integer Twitter ID
twitter.bio string Twitter Bio
twitter.followers integer Count of Twitter followers
twitter.following integer Count of Twitter friends
twitter.location string Twitter location
twitter.site string Twitter site
twitter.avatar string HTTP Twitter avatar
angellist.handle string AngelList handle
angellist.bio string AngelList bio
angellist.blog string AngelList blog
angellist.site string AngelList site
angellist.followers integer AngelList followers count
angellist.avatar string AngelList avatar url
crunchbase.handle string Crunchbase handle
logo string SRC of company logo
emailProvider boolean is the domain associated with a free email provider (i.e. Gmail)?
type string The company’s type, either education, government, nonprofit, private, public, or personal.
phone string International headquarters phone number
tech array Array of technology tags
indexedAt string date The time at which we indexed this data

Domain lookup

The Company API allows you to look up a company by their domain. Alongside the domain you may also provide any additional attributes you have about the company, such as their company name or twitter handle. Including more detail will help us be more accurate when searching.

The supported parameters are:

param Description
domain string The domain to look up. This is required.
company_name string The name of the company.
linkedin string The LinkedIn URL for the company.
twitter string The Twitter handle for the company.
facebook string The Facebook URL for the company.
To look up a company by domain name, run the following. The command will either return a 404 (in which case the company wasn’t found), a 422 if the domain name is invalid (doesn’t exist, or doesn’t resolve), a 202 indicating the lookup has been queued, or a 200 returning the relevant company.
curl 'https://company.corpping.com/v2/companies/find?domain=stripe.com' \
        -u {key}:

This endpoint retrieves a company by domain name. If we can find the company we’ll return a 200 status containing the record’s attributes.

Sometimes we’ll need to asynchronously lookup the company, in which case we’ll return an empty 202 status. Either try the same request again in a few minutes to get the full response, or register a webhook to be notified when we’ve finished searching for a company.

If we can’t find any information associated with the domain name, we’ll return a 404 status.

HTTP Request

GET https://company.corpping.com/v2/companies/find?domain=:domain

Where :domain is the company’s domain name.

HTTP GET params

You can also pass the following optional parameters along when looking up companies.

param Description
webhook_id string Custom identifier for the webhook request.

Response types

Code Description
200 Successful lookup, company encoded in the response body.
202 Asynchronously looking up the company.
404 Company not found.
422 Domain name is invalid.

Flagging

To flag a company’s data as incorrect

curl 'https://company.corpping.com/v1/companies/3823d7e8-4710-4e6c-b4cf-4e7c151d1767/flag' \
        -XPOST \
        -d 'name=Stripe' \
        -u {key}:

While we do our best to always return accurate data sometimes we can make mistakes. The flagging endpoint allows you to let us know if a company doesn’t seem quite right. You can flag a company as incorrect and also optionally pass through a correct set of attributes.

We look into all the flagging we receive and incorporate fixes into future results.

HTTP Request

POST https://company.corpping.com/v1/companies/:id/flag

Where :id is the id of the company you’d like to flag as inaccurate.

HTTP POST params

You can also optionally pass to us corrected versions of any of the company’s attributes we sent you.

param Description
name string (optional) Name of company
tags array List of market categories the company is involved in
description string Description of the company
raised integer Total amount raised
location string Address of company
facebook_handle string (optional) Facebook ID or screen name
twitter_handle string (optional) Twitter screen name
linkedin_handle string (optional) LinkedIn URL (i.e. /pub/martin-beiber/78/929/ab5)
angellist_handle string (optional) AngelList handle.
crunchbase_handle string Crunchbase handle
employees integer Amount of employees
logo string SRC of company logo
email_provider boolean is the domain associated with a free email provider (i.e. Gmail)?
type string Type of company (education, government, nonprofit, private, public, personal)

Response types

Code Description
200 Successful received, we will look into the issue.
404 Company not found.

CompanyDiscover API

Our CompanyDiscover API lets you search for companies via specific criteria. For example, you could search for all companies with a specific funding, that use a certain technology, or that are similar to your existing customers.

Attributes

The JSON encoded response looks like this:

{
  "total": 605410,
  "page": 1,
  "results": [
    {
      "name": "Corpping",
      "domain": "corpping.comm",
      "//": "..."
    }
  ]
}

Every search response includes the following three fields:

Name Description
total Total amount of companies matching the search
page Page number for pagination
results Array of company responses

Request

Our search API lets you filter by over 30 different attributes. For example, to find all companies using Marketo that have raised over 100k run:

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=and:(tech:marketo raised:100000~)' \
  --data-urlencode 'sort=alexa_asc' \
  -u {key}:

We support over 30 different query parameters to help you filter results and find the companies you’re looking for.

Each company returned will count towards the monthly quota.

URL

GET https://discovery.corpping.com/v1/companies/search

Response codes

Code Description
200 Successful lookup, search response encoded in the response body.
422 Invalid search (request has a malformed query param).

Params

The query param is required to make search.

Param Description
query string Search query string.

You can also pass the following optional parameters along when searching for companies.

Param Description
page integer Which results page to show (default is 1).
page_size integer The amount of results to return per page.
limit integer How many paginated results to return in total.
sort string Which order results are returned in.

Pagination

To retrieve an additional page pass the page option:

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=twitter_followers:10000~' \
  --data-urlencode 'page=2' \
  -u {key}:

Search requests return a maximum of 10 results per page. You can paginate through results and receive the next set by incrementing the page param.

Sorting

To sort by a specific attribute using the sort option.

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=tech:marketo' \
  --data-urlencode 'sort=google_rank' \
  -u {key}:

To sort in a particular direction append _asc or _desc to the sort option:

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=tech:marketo' \
  --data-urlencode 'sort=alexa_asc' \
  -u {key}:

By default search results are sorted by the best match available. You can change this to a specific sort using the sort parameter and one of the values below.

You can toggle between ascending and descending sorts by appending _asc and _desc respectively.

Sort Description
score Default sort
alexa_rank Alexa ranking
employees Number of employees
google_rank Google rank
market_cap Market cap for public companies
raised Amount of funding raised
twitter_followers Number of Twitter followers

Queries

Queries are space separated key colon values. For example to find all companies with an Alexa rank between 1 & 1000, 30 employees or more, and based in SF the query would look like this:

  alexa_rank:0~1000 employees:30~ city:"San Francisco"

As you can see, you can escape values by using quotes. You can also include sub queries by using parenthesis:

  and:(tech:stripe raised:10000~)

Queries to the CompanyDiscover API can be as complex or as simple as you need them to be. Queries are passed along as strings in the query parameter using the type:value format. Take a look at the examples on the right.

Data types

Every query option is one of the following data types:

type Description
string Letters
integer Number
range Range of numbers separated by a tilde (~).
Omit the first or last integer to scan the full range.

Fields

The following fields are supported:

Param Description
domain string Exact domain match
name string Fuzzy name match
description string Fuzzy description match
and query AND query (see below)
or query OR query (see below)
alexa_rank range Global Alexa rank
alexa_us_rank string US Alexa rank
google_rank range Google Page Rank
location string Fuzzy long form address match
state string Two letter state code
city string Long form city name of headquarters
country string Two letter country code of headquarters
angellist string AngelList handle
crunchbase string Crunchbase handle
employees range Headcount
facebook string Facebook handle
linkedin string LinkedIn handle
twitter string Twitter handle
twitter_followers range Number of Twitter followers
twitter_following range Number of Twitter friends
market_cap range Market cap
ticker string Stock ticker symbol
raised range Amount of funding raised
industry string Categorization industry
sub_industry string Categorization sub-industry (see a complete list)
sector string Categorization sector (see a complete list)
tag string Categorization tags (see a complete list)
similar string Domain name of similar company (see below)
tech string Tech used (see below)
type string Company type (education/government/nonprofit/private/public/personal)
has string Only return companies who have data for the given field. Aliased as ‘exists’
hasnt string Only return companies who don’t have data for the given field. Aliased as ‘missing’

AND/OR queries

By default queries use an AND search - results have to satisfy all parameters. To change this behavior use the or query type and pass a sub-query:

  or:(twitter_followers:10000~ type:nonprofit)

For example, to find all companies that have at least 10000 Twitter followers or are charities:

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=or:(twitter_followers:10000~ type:nonprofit)' \
  -u {key}:

By default, queries are are filtered by an AND match. That is, if you provide multiple query options, results must match all of them of them. You can change this behavior to OR matching (where matches to all criteria are preferred, but not required) by using a OR query.

Similar queries

You can search for companies similar to other ones by domain:

  similar:stripe.com

For example, to find any companies similar to Salesforce:

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=similar:salesforce.com' \
  -u {key}:

To find ‘look-alike’ companies–companies that are similar to each other–you can use the similar query. Pass a company’s domain and we’ll try and find similar companies. This is particularly useful for taking your existing customer list and finding new leads.

Tech queries

To search for companies using particular front-end technologies use the tech query:

  tech:stripe tech:customer_io tech:segment

For example, to find any companies that use Google Apps sorted by Alexa score:

curl 'https://discovery.corpping.com/v1/companies/search' \
  -G --data-urlencode 'query=tech:google_apps' \
  --data-urlencode 'sort=alexa_asc' \
  -u {key}:

Whenever we index a company’s website, we also detect any technologies they’re using such as their analytics provider, email provider, or payments provider. We then surface over 60 different technologies in our search API letting you filter by them.

You can find a full list of technologies we index here.

CompanyTitles API

The CompanyTitles API lets you fetch contacts and emails associated with a company, employment role, seniority, and job title.

To search for people by domain name, run the following.

curl 'https://prospector.corpping.com/v1/people/search' \
        -G --data-urlencode 'domain=twitter.com' \
        --data-urlencode 'role=marketing' \
        -u {key}:

This endpoint returns an array of people who work at a specific company.

HTTP Request

GET https://prospector.corpping.com/v1/people/search

HTTP GET params

You can also pass the following parameters along when searching for people.

param Description
domain string (required) Domain of the company you want to search against.
role string (optional) Employment Role (view list).
seniority string (optional) Employment Seniority (view list).
title string (optional) Job title to filter by.
titles[] string (optional) Multiple job titles to filter by. You can specify this param multiple times to search for multiple titles.
name string (optional) Name of an individual to filter by.
limit integer (optional) Limit the number of maximum results returned in the response (default is 5, max is 20).

Response Types

Code Description
200 Successful lookup, person encoded in the response body.
406 Validation error

Response body

The JSON encoded response looks like this.

[
  {
    "id": "7416592A-A0D5-4AE5-ACB0-03156E444E9C",
    "name": {
      "givenName": "Harlow",
      "familyName": "Ward",
      "fullName": "Harlow Ward"
    },
    "title": "Co Founder at Corpping",
    "email": "harlow@corpping.comm"
  }
]
Attribute Description
id string Internal ID
name.givenName string First name of person
name.familyName string Last name of person
name.fullName string Full formatted name of person
title string Employment title

Email lookup

To retrieve people’s emails run the following:

curl 'https://prospector.corpping.com/v1/people/:id/email' \
        -u {key}:

This endpoint returns a person’s email address.

Calls to this endpoint can take a while if we haven’t cached the results, anything from 3 to 5 seconds. This is expected–feel free to parallelize requests to compensate.

Email addresses may be nil if we can’t find them. Only responses containing an email address go against your quota. We do our best to verify emails are correct, but it’s not perfect. We’re currently seeing about 80% accuracy for email addresses.

HTTP Request

Where :id is a Person ID from the Prospector search results.

GET https://prospector.corpping.com/v1/people/:id/email

Response Types

Code Description
200 Successful lookup, email encoded in the response body.
406 Validation error

Response body

The JSON encoded response looks like this.

{
  "verified": true,
  "email": "harlow@corpping.comm"
}
Attribute Description
verified boolean Whether or not we’ve managed to make an MX check against the email
email string The person’s email address

CompanyIP API

Our CompanyIP API takes an IP address, and returns the company associated with that IP. This is especially useful for de-anonymizing traffic on your website, analytics, and customizing landing pages for specific company verticals.

Powering Reveal is a unique dataset that combines both public and proprietary sources to give you an insight into the companies visiting your website whatever their size, even if they don’t have their own public ASN block.

The CompanyIP API is currently under limited release.
To get access to the API, please contact us.

Lookup IP addresses

To use the CompanyIP API, send us an IP address and we’ll return the company domain and information associated. If we can’t match the IP to a company, we’ll return a 404 HTTP status instead of a 200.

Attributes

The JSON encoded response looks like this.

{
  "ip": "45.116.230.22",
  "fuzzy": true,
  "domain": "segment.com",
  "company": {
    "name": "Segment",
    "tags": [
      "Software",
      "SAAS",
      "B2B",
      "Information Technology & Services",
      "Technology",
      "Internet"
    ],
    "metrics": {
      "alexaUsRank": 23403,
      "alexaGlobalRank": 26266,
      "employees": 95,
      "employeesRange": "51-250",
      "raised": 44600000
    },
    "...":  "..."
  }
}

In the case above, ‘...’ represents a truncated company response. You can find the full company response under the Company Attributes section.

Attribute Description
ip string IP address that was looked up
fuzzy boolean False if the company has their own dedicated ASN network, otherwise true.
domain string The matched company domain
company object A full company response

HTTP Request

To lookup an IP address, run the following:
curl https://reveal.corpping.com/v1/companies/find?ip=45.116.230.22 \
        -u {key}:

GET https://reveal.corpping.com/v1/companies/find

HTTP GET parameters

The following parameters are supported.

Parameter Description
ip string (required) IP address to lookup

Response types

Code Description
200 Successful lookup
404 Company not found
422 Invalid parameters

CompanyFullFill API

Company Autocomplete is a free API that lets you auto-complete company names and retreive logo and domain information.

Send requests with paritial company name to endpoint:

curl 'https://autocomplete.corpping.com/v1/companies/suggest?query=stripe'

The JSON encoded response looks like this:

[
  {
    "domain": "stripe.com",
    "logo": "https://logo.corpping.com/stripe.com",
    "name": "Stripe"
  },
  {
    "domain": "stripesgroup.com",
    "logo": "https://logo.corpping.com/stripesgroup.com",
    "name": "Stripes Group"
  }
]

HTTP Request

GET https://autocomplete.corpping.com/v1/companies/suggest?query=:name

Where :name is the partial name of the company.

HTTP Response

Responses will include the following three fields:

Name Description
domain Domain name of company
logo URL to logo
name Name of the company

CompanyLogo API

If you’re only interested in a Company’s logo, and don’t need any other data about the company, you can use our free CompanyLogo API.

Access to the API is unauthenticated and doesn’t require a Corpping account. We also provide some nify options listed below. If we can’t find a logo we’ll return a 404 status.

You can call the API directly from an html img tag - images are returned inline. For example:

<img src="https://logo.corpping.com/stripe.com">

Return’s Stripe’s logo.

To alter the size or greyscale, pass some query params:

<img src="https://logo.corpping.com/stripe.com?size=200&greyscale=true">

HTTP Request

GET https://logo.corpping.com/:domain

Where :domain is the domain of the company.

HTTP GET params

You can also optionally pass us the following parameters.

param Description
size integer (optional) image size: length of longest side in pixels (default is 128)
format string (optional) image format, either "png" or "jpg" (defaults to png)
greyscale boolean (optional) Desaturates image if passed (defaults to false)

Default images

Sometimes we can’t find a logo and image requests will return with a 404 response code. Rather than having a broken image show up you can use the onerror event to replace the image with a default of your choosing.

Specify your own logo with the og:logo Open Graph tag.

<meta property="og:logo" content="http://yourdomain.com/logo.png" />

Or to specify different sizes add multiple meta tags with a size attribute.

<meta property="og:logo" content="/logo.png" size="150x150" />
<meta property="og:logo" content="/logo.png" size="250x250" />
<meta property="og:logo" content="/logo.png" size="500x500" />

While we normally try and detect a company’s logo using signals like their Twitter or Facebook account, if you control a domain you can indicate which logo you’d like used.

Just add a og:logo Open Graph meta tag to your index page under the root domain, and point its content attribute to your logo of choice. We support png and jpg formats.

* Commercial use of the CompanyLogo API requires a link attribution on any page in which the logo is displayed - i.e “Logos provided by Corpping”.