Company API Overview

Use the company method with a domain as the lookup parameter to find information about a specific company by domain. You must also include the apiKey parameter in the query. This endpoint supports GET requests only.

Getting Started

As you get started implementing the Company API, there are a few resources that can help you out. Below we’ve listed a few libraries and services.

Libraries

  • Java Client for FullContact API (v2) by FullContact - A Java client to access most of FullContact’s v2 API endpoints, including Person, Company, Card Reader, Disposable Email, Name, and more.

Other Resources

Lookup by Domain

Use this method to request more information about a specific company by domain.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com'

Parameters

apiKey

This API key is assigned to you by FullContact. It is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com'

domain

The domain of the company being looked up. For example, fullcontact.com.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com'

keyPeople (optional)

If true, a list of Executive and VP level employees at this company will be returned under the keyPeople field.

prettyPrint (optional)

The prettyPrint parameter can be used to disable prettyprint formatting on the API response.

  • false - results will be returned with out formatting (e.g. new lines will be removed).
  • true - results will be returned with various stylistic formatting conventions enabled.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&prettyPrint=false'

callback (optional)

If specified, the response will be wrapped as JSONP in a function call. For example, by specifying callback=myCallback the resulting JSON will be:

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&callback=myCallback'

Example Response

myCallback ({
    ...response...
})

webhookUrl (required for webhooks only)

View Webhook flow diagram

For the webhookUrl parameter, enter the callback url you'd like the data to be posted back to (ie. https://mydomain.com/callback/listener). Keep in mind that the URL must be properly escaped (i.e. ampersands) and/or URL encoded if not enclosed in single or double quotes.

When you include the webhookUrl parameter in your API request, an HTTP POST request will be triggered to the URL you've specified. The payload of the response POSTed to the webhook URL is JSON. This is the format regardless of whether the initial request to v2/Person was to the .json, .xml or .html version of the person endpoint.

When testing webhooks during development, we recommend intercepting the webhook POST requests locally, or using a web-based webhook testing service like Requestb.in. Requestb.in lets you debug webhooks by capturing and logging the asynchronous requests made when events happen. Create a Requestb.in URL and insert the URL provided into the webhookUrl parameter of your API request. All messages POSTed to the Requestb.in URL will be available almost immediately after you initiate a webhook-based request.

NOTE: We will make 3 attempts to deliver the payload, waiting a minimum of 2 seconds between each attempt. If a 200 response is not received within 3 attempts, the request will be dropped.

BLACKLISTING: If FullContact can’t deliver at least 10 consecutive, successful messages to a specified URI over a 5 minute period, we will temporarily impose a 5 minute blacklisting of the URI. After the 5 minutes has elapsed, the blacklist will be automatically removed and FullContact will resume webhook delivery attempts.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&webhookUrl=myWebhookUrl'

Example Encoded Webhook URL

$ curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&webhookUrl=http://mydomain.com/webhook'

webhookId (optional)

You can enter anything you want here, we will just pass it back in the response. This allows you to track the webhook if you wish.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&webhookUrl=myWebhookUrl&webhookId=myId'

Webhook Example Response (JSON)

$ curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/lookup.json?domain=fullcontact.com&webhookUrl=myWebhookUrl&webhookId=myId'

{
    "result":
    {
        "status":200,
        "requestId":"2fc35530-4887-4947-9bbb-08cf1ae1db56",
        "category":[
            {"name":"Other","code":"OTHER"}
        ],
        "logo":"https://d2ojpxxtu63wzl.cloudfront.net/static/1bacd7306731a30d2a",
        "website":"https://www.fullcontact.com",
    /* results truncated */
    }
}

Example Responses

The API responds with JSON.

{
  "status" : 200,
  "requestId" : "9ffd07d9-2ef9-4fd6-994a-228472a5be6f",
  "category" : [ {
    "name" : "Other",
    "code" : "OTHER"
  } ],
  "logo" : "https://d2ojpxxtu63wzl.cloudfront.net/static/e9f3aeb8965684906efa7ae514988ffb_0837a93ef09a70f8b9ff73efac18176225fd0b9cb8bf84a60c5926701b4c5033",
  "website" : "https://www.fullcontact.com",
  "languageLocale" : "en",
  "organization" : {
    "name" : "FullContact Inc.",
    "approxEmployees" : 50,
    "founded" : "2010",
    "overview" : "Solving the world's contact information problem!",
    "contactInfo" : {
      "emailAddresses" : [ {
        "value" : "support@fullcontact.com",
        "label" : "support"
      }, {
        "value" : "sales@fullcontact.com",
        "label" : "sales"
      } ],
      "phoneNumbers" : [ {
        "number" : "+1 (888) 330-6943",
        "label" : "other"
      } ],
      "addresses" : [ {
        "addressLine1" : "1755 Blake Street",
        "addressLine2" : "Suite 450",
        "locality" : "Denver",
        "region" : {
          "name" : "Colorado",
          "code" : "CO"
        },
        "country" : {
          "name" : "United States",
          "code" : "US"
        },
        "postalCode" : "80202",
        "label" : "work"
      } ]
    },
    "links" : [ {
      "url" : "https://www.fullcontact.com/developer",
      "label" : "other"
    }, {
      "url" : "https://fullcontact.com/blog",
      "label" : "blog"
    }, {
      "url" : "https://www.youtube.com/watch?v=koFtyUDbYak",
      "label" : "youtube"
    }, {
      "url" : "https://www.fullcontact.com/home/feed",
      "label" : "rss"
    }, {
      "url" : "https://www.fullcontact.com/feed",
      "label" : "rss"
    }, {
      "url" : "https://www.fullcontact.com/comments/feed",
      "label" : "rss"
    } ],
    "images" : [ {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/edaa53d9a080aea37ddfb85d775620a9_98a2d7beef6a5b4a53f43da4dd1a90bda21dc18f755394fdbf9b6cf3283853a0",
      "label" : "twitter"
    }, {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/1bacd7306731a30d2a9f024eeb1dcff1_94d77dcdedbfe40707ac4a75ca4f4d2978bffc20b2e33a3288ea9e4d47f5af6c",
      "label" : "twitter"
    }, {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/3f64db7ba9331fbd1e4cc11655e2d3d4_a2477a83cafc8a98d5533f3617f0b1db2796ad0826482e2eabdc8d3345d70c17",
      "label" : "twitter"
    }, {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/ee07ac81180408fde663426d3b0afb3f_3a1154347631c037b9bd2b2f33d4cbc8511d58f5c11ad3cbbc319957d1a5149b",
      "label" : "pinterest"
    }, {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/80885c5e8b570e69bdc55d29aad115cd_a1ce9fb51ea43971d861e452034056d807422a391ac8e27f76ee4a9e803698d1",
      "label" : "googleplus"
    }, {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/4be5211e4b0129d1c8d41e84f257f343_3d84b3de68d6060243972af12a8ca67c4a595fd86a4419d50bf429e6d778ce2d",
      "label" : "other"
    }, {
      "url" : "https://d2ojpxxtu63wzl.cloudfront.net/static/7e9aa6402ff2975e297a01243c358619_c0b8d4a63a52f4a47106494561c0332b79f848b40fcbe92336a0a17b843f44f8",
      "label" : "other"
    } ],
    "keywords" : [ "APIs", "Boulder", "Contact Management", "Denver", "Developer APIs", "Social Media", "Techstars" ]
  },
  "socialProfiles" : [{
    "bio" : "We're solving the world's contact information problem. Get your contacts under control with @FullContactApp & check out @FullContactAPI for our APIs.",
    "followers" : 6277,
    "following" : 1758,
    "typeId" : "twitter",
    "typeName" : "Twitter",
    "url" : "https://twitter.com/FullContactInc",
    "username" : "FullContactInc",
    "id" : "142954090"
  }, {
    "bio" : "The API that turns partial contact information into full contact information. We provide data enrichment, de-duplication, normalization, and much more.",
    "followers" : 5032,
    "following" : 2444,
    "typeId" : "twitter",
    "typeName" : "Twitter",
    "url" : "https://twitter.com/FullContactAPI",
    "username" : "FullContactAPI",
    "id" : "340611236"
  }, {
    "bio" : "Keep your contact information clean, complete & current across all your address books.",
    "followers" : 3171,
    "following" : 1561,
    "typeId" : "twitter",
    "typeName" : "Twitter",
    "url" : "https://twitter.com/FullContactApp",
    "username" : "FullContactApp",
    "id" : "451688048"
  }, {
    "bio" : "FullContact's address book brings all of your contacts into one place and keeps them automatically up to date on the web, as well as on your iPhone and iPad. Add photos to your contacts. Find them on social networks like Twitter, LinkedIn and of course AngelList. It's the address book that busy professionals from any walk of life can appreciate, and best of all it's free. For developers, the suite of FullContact APIs builds powerful, complete profiles of contacts that can be included in any application.",
    "followers" : 259,
    "typeId" : "angellist",
    "typeName" : "AngelList",
    "url" : "https://angel.co/fullcontact",
    "username" : "fullcontact"
  }, {
    "bio" : "FullContact provides a suite of cloud-based contact management solutions for businesses, developers, and individuals.",
    "typeId" : "crunchbasecompany",
    "typeName" : "CrunchBase",
    "url" : "http://www.crunchbase.com/organization/fullcontact",
    "username" : "fullcontact"
  }, {
    "bio" : "FullContact is the API that keeps contact information current. We build APIs that developers can integrate into their applications using any language.",
    "followers" : 28,
    "following" : 55,
    "typeId" : "pinterest",
    "typeName" : "Pinterest",
    "url" : "http://www.pinterest.com/fullcontact/",
    "username" : "fullcontact"
  }, {
    "bio" : "All your contacts in one place and automatically up-to-date. we're solving the world's contact information problem at https://www.fullcontact.com.",
    "typeId" : "google",
    "typeName" : "GooglePlus",
    "url" : "https://plus.google.com/u/0/107620035082673219790",
    "id" : "107620035082673219790"
  }, {
    "typeId" : "klout",
    "typeName" : "Klout",
    "url" : "http://klout.com/FullContactAPI",
    "username" : "FullContactAPI",
    "id" : "33777001971317895"
  }, {
    "bio" : "FullContact is solving the world's contact information problem by providing APIs to software developers to keep contact information clean, complete and current. FullContact provides identity resolution for all of the disparate pieces of contact information out there on the web. We do this by aggregating billions of contact records, all with numerous attributes, including quality, freshness and frequency. Our patent pending algorithms process all of this data and automatically produce clean, accurate full contact records. As a final step, we then check each data element to make sure that it's publicly available before providing it to our customers. FullContact is a TechStars Boulder 2011 Company.",
    "typeId" : "linkedincompany",
    "typeName" : "LinkedIn",
    "url" : "https://www.linkedin.com/company/fullcontact-inc-",
    "username" : "fullcontact-inc-",
    "id" : "2431118"
  } ],
  "traffic" : {
    "topCountryRanking" : [ {
      "rank" : 7770,
      "locale" : "us"
    }, {
      "rank" : 11728,
      "locale" : "in"
    }, {
      "rank" : 11388,
      "locale" : "gb"
    } ],
    "ranking" : [ {
      "rank" : 18640,
      "locale" : "global"
    }, {
      "rank" : 7770,
      "locale" : "us"
    } ]
  }
}

Response Schema

The following is a description of response schema for domain lookup. It includes every possible field, collection, and value you can expect to receive. Note that certain fields and collections will only appear in the response when the data is available.

{
  "status" : "type":"number",
  "requestId" : "type":"string",
  "category" : [ {
     "name" : "type":"string",
     "code" : "type":"string" // Currently "ADULT", "EMAIL_PROVIDER", "EDUCATION", "SMS", "OTHER"  
   } ],   
  "logo" : "type":"string",
  "website" : "type":"string",
  "languageLocale" : "type":"string",
  "onlineSince" : "type":"string",  // ISO 8601 Date of the first known online presence for this domain
  "redirectsTo" : "type":"string",  // URL to which this domain redirects
  "organization" : {
    "name" : "type":"string",
    "approxEmployees" : "type":"number",
    "founded" : "type":"string",   // ISO 8601 Date
    "overview" : "type":"string",
    "contactInfo" : {
      "emailAddresses" : [ {
        "value" : "type":"string",
        "label" : "type":"string"   // Current labels include "other", "support", "sales", "publicity", "jobs", or "general"
      } ],
      "phoneNumbers" : [ {
        "number" : "type":"string",
        "label" : "type":"string"
      } ],
      "addresses" : [ {
        "addressLine1" : "type":"string",
        "addressLine2" : "type":"string",
        "locality" : "type":"string",
        "region" : {
          "name" : "type":"string",
          "code" : "type":"string"
        },
        "country" : {
          "name" : "type":"string",
          "code" : "type":"string"   // ISO 3166-1 Alpha 2
        },
        "postalCode" : "type":"string",
        "label" : "type":"string"
      } ]
    },
    "keyPeople": [ {
      "name" : "type":"string",
      "title" : "type":"string",
      "link" : "type":"string"   // A link to Person API for this individual. You will need to add your API Key.
    } ],
    "links" : [ {
      "url" : "type":"string",
      "label" : "type":"string"
    }],
    "images" : [ {
      "url" : "type":"string",
      "label" : "type":"string"
    }],
    "keywords" : [ "type":"string" ]
  },
  "socialProfiles" : [ {
    "bio" : "type":"string",
    "followers" : "type":"number",
    "following" : "type":"number",
    "typeId" : "type":"string",
    "typeName" : "type":"string",
    "url" : "type":"string",
    "username" : "type":"string",
    "id" : "type":"string"
  }],
  "traffic" : {
    "topCountryRanking" : [ {
      "rank" : "type":"number",
      "locale" : "type":"string"   // Up to three results of type ISO 3166-1 Alpha 2
    } ],
    "ranking" : [ {
      "rank" : "type":"number",
      "locale" : "type":"string"   // Up to two results, of type "global" and/or "us"
    } ]
  }
}

Error responses

The Company API will return a 404 error in two different cases, which you can distinguish using the reasonCode field:

  • reasonCode="NOT_REGISTERED": The domain is not a valid registered domain
  • reasonCode="NOT_FOUND": The domain is valid (i.e., has DNS info), but our search didn't find any pertinent information to return

Lookup by Company Name

Use this method to request more information about a specific company by name.

Usage of this method is limited based on your current API plan. Please visit the Developer Portal to see your allowed monthly usage for the Feature - Company Search metric under the STATS tab.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/search.json?companyName=fullcontact'

Parameters

companyName

The name of the company to search for. Common words like "Inc." will be ignored.

sort (optional)

Controls how results will be sorted. There are three options:

  • traffic (default): Sort high-traffic domains to the top
  • relevance: Sort by how closely the company name matches
  • employees: Sort companies with many employees to the top

location (optional)

If supplied, only companies matching given location will be returned. The location is a general location where one can include any combination of locality, region or country as input. For example, location=Denver,%20CO

locality (optional)

If supplied, only companies matching given locality/city will be returned. For example, locality=New%20York or locality=Dallas

region (optional)

If supplied, only companies matching given region/state will be returned. For example, region=New%20York or region=NY

country (optional)

If supplied, only companies matching given country will be returned. For example, country=United%20States or country=US

prettyPrint (optional)

The prettyPrint parameter can be used to disable prettyprint formatting on the API response.

  • false - results will be returned with out formatting (e.g. new lines will be removed).
  • true - results will be returned with various stylistic formatting conventions enabled.

callback (optional)

If specified, the response will be wrapped as JSONP in a function call. For example, by specifying callback=myCallback the resulting JSON will be:

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/company/search.json?companyName=fullcontact&callback=myCallback'

Example Response

myCallback ({
    ...response...
})

Example Responses

The API responds with a JSON array with one entry for each potentially-matching company.

[
  {
    "lookupDomain": "fullcontact.com",
    "orgName": "FullContact Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/static/91a060eb8afdbd9c89fe23ed3a658a84_c1315c9e876cb92fee969e95c92e5fc5930d1b8f5d563d34b5e6fc4c58d8fa7e_150x150",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "companyApiLink": "https://api.fullcontact.com/v2/company/lookup?domain=fullcontact.com&apiKey="
  },
  {
    "lookupDomain": "brewster.com",
    "orgName": "FullContact Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/static/d0c63e9b9d53ce25e7a3f48da3beb9d2_d66ec972fd330acf55d5b5c8ad06a787909f99fc2166363abd5b56d458ba6e1e_150x150",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "companyApiLink": "https://api.fullcontact.com/v2/company/lookup?domain=brewster.com&apiKey="
  },
  {
    "lookupDomain": "rainmaker.cc",
    "orgName": "FullContact Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/static/33739df1ce824fd2d2669211ed682196_8d3b1c8ce64909d95c1274bf9ed70ef3ae98e71ef58337e87bb2d19780dafcad_150x150",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "companyApiLink": "https://api.fullcontact.com/v2/company/lookup?domain=rainmaker.cc&apiKey="
  },
  {
    "lookupDomain": "fullcontact.co",
    "orgName": "FullContact Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/static/a1e17040e70cf23485d374647360094e_8580f27f54cad641ebb634c14f96267d570261eea55416210f667ea5e10aecab_150x150",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "companyApiLink": "https://api.fullcontact.com/v2/company/lookup?domain=fullcontact.co&apiKey="
  },
  {
    "lookupDomain": "ngame.com",
    "orgName": "FullContact Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/static/d0c63e9b9d53ce25e7a3f48da3beb9d2_d66ec972fd330acf55d5b5c8ad06a787909f99fc2166363abd5b56d458ba6e1e_150x150",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "companyApiLink": "https://api.fullcontact.com/v2/company/lookup?domain=ngame.com&apiKey="
  }
]

Response Schema

The following is a description of the response schema for company name search. It includes every possible field, collection, and value you can expect to receive. Note that certain fields and collections will only appear in the response when the data is available.

{
  "lookupDomain": "type":"string", // The domain of the company. Can be used to look up full details on this company (see companyApiLink below)
  "orgName": "type":"string",
  "logo": "type":"string",
  "location": {
    "locality": "type":"string",
    "region": {
      "name": "type":"string",
      "code": "type":"string"
    },
    "country": {
      "name": "type":"string",
      "code": "type":"string" // ISO 3166-1 alpha-2
    }
  },
  "score": "type":"number", // if using relevance sort, a number between zero and one indicating how closely this result matches
  "companyApiLink": "type":"string"
}