Skip to content

CompanyClient

Jump to bottom
Nithin Subhash edited this page Apr 3, 2020 · 3 revisions

CompanyClient

This class provides an interface to the V3 Company Enrich and Search endpoints. Once the client library is installed, CompanyClient can be directly imported from it and an instance can be created using the API Key, as follows.

from fullcontact import CompanyClient
company_client = CompanyClient(<API_KEY>)

Methods

enrich(headers=None, delay=1, max_retries=5, **query)

This method has the same parameters as PersonClient.enrich(), but hits FullContact Company Enrich API instead of Person Enrich API and accepts different fields for query.

  • Parameters: Same as PersonClient.enrich(), but the supported fields in query are different. Supported fields are mentioned in the next section.
  • Returns: CompanyEnrichResponse object
  • Return type: fullcontact.response.company_response.CompanyEnrichResponse

enrich_async(headers=None, delay=1, max_retries=5, **query)

This method has the same parameters as the CompanyClient.enrich() method, but works asynchronously using a concurrent.futures.thread.ThreadPoolExecutor.

search(headers=None, delay=1, max_retries=5, **query)

This method has the same parameters as CompanyClient.enrich(), but hits FullContact Company Search API instead of Company Enrich API and accepts different fields for query.

  • Parameters: Same as CompanyClient.enrich(), but the supported fields in query are different. Supported fields are mentioned in the next section.
  • Returns: CompanySearchResponse object
  • Return type: fullcontact.response.company_response.CompanySearchResponse

search_async(headers=None, delay=1, max_retries=5, **query)

This method has the same parameters as the CompanyClient.enrich() method, but works asynchronously using a concurrent.futures.thread.ThreadPoolExecutor.

Query

For company enrich and search operations, the query has to be provided as kwargs. The query parameters are aligned with the FullContact Company Enrichment Requests

Valid query parameter for enrich:

  • domain [str] - The domain name of the company to lookup.

Valid query parameter for search:

  • companyName [str] (required) - The name of the company to search for.
  • ** sort** [str] (optional) - Controls how results will be sorted. Valid values: traffic, relevance, employees
  • location [str] (optional) - If provided, only companies matching given location will be returned.
  • locality [str] (optional) - If provided, only companies matching given locality/city will be returned.
  • region [str] (optional) - If provided, only companies matching given region/state will be returned.
  • country [str] (optional) - If provided, only companies matching given country will be returned.

Additional optional parameters that can be passed in enrich/search query:

  • webhookUrl [str] (optional) - If a valid webhook url is passed through this parameter, the request will be queued and result will be POSTed to the provided webhook URL, once the processing has been completed.

Response

The responses of enrich() and search() methods are CompanyEnrichResponse of type fullcontact.response.company_response.CompanyEnrichResponse and CompanySearchResponse object of type fullcontact.response.company_response.CompanySearchResponse, respectively. The responses are aligned with the Company Enrichment/Search Response.

The response of enrich_async() or search_async() method is a Future object of type concurrent.futures.Future. If successful, the Future.result() will return a CompanyEnrichResponse or a CompanySearchResponse, based on the method.

CompanyEnrichResponse

CompanyEnrichResponse provides the below instance variables and methods

  • is_successful [bool] - True if the response status code is 200, 202 or 404. Else, False.
  • response [requests.Response] - The actual Response object received from requests.post operation, that makes the API call. This may be helpful in debugging.
  • get_status_code() -> [int] - Returns the HTTP status code received.
  • get_message() -> [str] - Returns the error message received from the API and the HTTP status message otherwise.
  • get_headers() -> [dict] - Returns the response headers as a dictionary.
  • raw() -> [dict] - Returns the response body converted to a dictionary.
  • get_summary() -> [dict] - Returns a dictionary with the Company summary extracted from raw response. This is the company enrich response without the details in it.
  • get_details() -> [dict] - Returns the details from the company summary as a dictionary.

CompanySearchResponse

CompanySearchResponse provides the below instance variables and methods

  • is_successful [bool] - True if the response status code is 200, 202 or 404. Else, False.
  • response [requests.Response] - The actual Response object received from requests.post operation, that makes the API call. This may be helpful in debugging.
  • get_status_code() -> [int] - Returns the HTTP status code received.
  • get_message() -> [str] - Returns the error message received from the API and the HTTP status message otherwise.
  • get_headers() -> [dict] - Returns the response headers as a dictionary.
  • raw() -> [list] or [dict] - Returns the response body with search results converted to a list if successful and otherwise, a dictionary with response converted to a dictionary.

Future

The Future object returned by the enrich_async() or search_async() method provides a method result() to retrieve the result once the processing is done. The output of this result() method will be a CompanyEnrichResponse or a CompanySearchResponse.
For details on Future objects, please refer: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future

Examples

  • Initialization
import os
from fullcontact import CompanyClient

company_client = CompanyClient(os.environ.get('FULLCONTACT_API_KEY'))
  • Synchronous enrich query
company_enrich_response = company_client.enrich(domain="fullcontact.com")

print(company_enrich_response.get_summary())
{
  "name": "FullContact Inc.",
  "location": "1755 Blake Street Suite 450 Denver CO, 80202 USA",
  "twitter": "https://twitter.com/fullcontact",
  "linkedin": "https://www.linkedin.com/company/fullcontact-inc-",
  "facebook": null,
  "bio": "FullContact is the most powerful fully-connected contact management platform for professionals and enterprises who need to master their contacts and be awesome with people.",
  "logo": "https://img.fullcontact.com/static/bb796b303166bd928f6c0968f15d4a4e_7ef85b2a563abd95ae07e815da2db916a5f8de4d82702388e546a66adc9eac44",
  "website": "https://www.fullcontact.com",
  "founded": 2010,
  "employees": 351,
  "locale": "en",
  "category": "Other",
  "dataAddOns": [
    {
      "id": "keypeople",
      "name": "Key People",
      "enabled": true,
      "applied": true,
      "description": "Displays information about people of interest at this company.",
      "docLink": "http://docs.fullcontact.com/api/#key-people"
    }
  ],
  "updated": "2020-04-03"
}
  • Synchronous search query
query = {
  "companyName": "fullcontact",
  "sort": "relevance",
  "location": "Colorado, USA",
  "locality": "Denver",
  "region": "Colorado",
  "country": "United States"
}

company_search_response = company_client.search(**query)

print(company_search_response.raw())
[
  {
    "lookupDomain": "blog.fullcontact.com",
    "orgName": "FullContact, Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/v1/thumbnail?size=128&url=https://img.fullcontact.com/static/6a43815ada39ec64b22d4589c11360b0_ac6d3981bba92f9df1c232eb98ad255a821acb3bbf66334c079b27f438b93653",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "score": 1
  },
  {
    "lookupDomain": "tryfullcontact.com",
    "orgName": "FullContact, Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/v1/thumbnail?size=128&url=https://img.fullcontact.com/static/d82fa6b4ff10b53af598b274bb9cafbc_f739aa5936447143d4fdcb242a112c62dcfba5c13400dfbcdc9b685ade1409f8",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "score": 0.976352277344633
  }
]
  • Asynchronous enrich query
company_enrich_future = company_client.enrich_async(domain="fullcontact.com")
company_enrich_response = company_enrich_future.result()

print(company_enrich_response.get_summary())
{
  "name": "FullContact Inc.",
  "location": "1755 Blake Street Suite 450 Denver CO, 80202 USA",
  "twitter": "https://twitter.com/fullcontact",
  "linkedin": "https://www.linkedin.com/company/fullcontact-inc-",
  "facebook": null,
  "bio": "FullContact is the most powerful fully-connected contact management platform for professionals and enterprises who need to master their contacts and be awesome with people.",
  "logo": "https://img.fullcontact.com/static/bb796b303166bd928f6c0968f15d4a4e_7ef85b2a563abd95ae07e815da2db916a5f8de4d82702388e546a66adc9eac44",
  "website": "https://www.fullcontact.com",
  "founded": 2010,
  "employees": 351,
  "locale": "en",
  "category": "Other",
  "dataAddOns": [
    {
      "id": "keypeople",
      "name": "Key People",
      "enabled": true,
      "applied": true,
      "description": "Displays information about people of interest at this company.",
      "docLink": "http://docs.fullcontact.com/api/#key-people"
    }
  ],
  "updated": "2020-04-03"
}
  • Asynchronous search query
query = {
  "companyName": "fullcontact",
  "sort": "relevance",
  "location": "Colorado, USA",
  "locality": "Denver",
  "region": "Colorado",
  "country": "United States"
}

company_search_future = company_client.search_async(**query)
company_search_response = company_search_future.result()

print(company_search_response.raw())
[
  {
    "lookupDomain": "blog.fullcontact.com",
    "orgName": "FullContact, Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/v1/thumbnail?size=128&url=https://img.fullcontact.com/static/6a43815ada39ec64b22d4589c11360b0_ac6d3981bba92f9df1c232eb98ad255a821acb3bbf66334c079b27f438b93653",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "score": 1
  },
  {
    "lookupDomain": "tryfullcontact.com",
    "orgName": "FullContact, Inc.",
    "logo": "https://d2ojpxxtu63wzl.cloudfront.net/v1/thumbnail?size=128&url=https://img.fullcontact.com/static/d82fa6b4ff10b53af598b274bb9cafbc_f739aa5936447143d4fdcb242a112c62dcfba5c13400dfbcdc9b685ade1409f8",
    "location": {
      "locality": "Denver",
      "region": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    },
    "score": 0.976352277344633
  }
]
Clone this wiki locally