python-fullcontact 1.0.0

A simple Fullcontact API client library

PersonClient

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

from fullcontact import PersonClient
person_client = PersonClient(<API_KEY>)

Methods

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

• Parameters:

  • headers [dict] (optional) - Any custom header that you wish to add to the request should be provided through this parameter as a dictionary. Authorization and Content-Type headers are added automatically, and need not be specified explicitly.

    An example use of this is to add Reporting Key, if required.
    headers = {"Reporting-Key": "clientXYZ"}

  • delay [int] (optional) - Delay in seconds to retry, in case of response status code 429 or 503. This value will be used as the base delay in exponential backoff. Default value is 1.

  • max_retries [int] (optional) - Maximum number of retries, in case of response status code 429 or 503. Maximum value allowed for this is 5.

  • query [kwargs] (required) - This is the query for performing person enrich operation and hence, is a required parameter. It should be provided as keyword arguments.

• Returns: PersonEnrichResponse object
• Return type: fullcontact.response.person_response.PersonEnrichResponse

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

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

• Parameters: Same as the parameters of enrich() method.
• Returns: Future object. Result is delivered through Future.result() method, once done.
• Return type: concurrent.futures.Future

Query

For person enrich operation, the query has to be provided as kwargs. The query parameters are aligned with the FullContact Enrich API Multi Field Request

If you have a dict query, that can be converted to kwargs by prepending ** to it.
person_client.enrich(**{"email": "[e-mail]", "phone": "1234567890"})

Valid query parameters:

• email [str] - One email address of the contact. Can accept cleartext, an MD5 or SHA-256 hash representation of the email address to query. Be certain to lowercase and trim the email address prior to hashing. There is a limit of 10 hashed emails.
• emails [list(str)] - One or many email addresses of the contact. Can accept cleartext, an MD5 or SHA-256 hash representation of the email address to query. Be certain to lowercase and trim the email address prior to hashing.
• phone [str] - Phone number of the contact. For international numbers a country code is required.
• phones [list(str)] - One or many phone numbers of the contact. For international numbers a country code is required.
• profiles [list(dict)] - A list of profiles. Below are the supported parameters for a profile.
  • service [str] - Service type of the profiles on the social platform. Either of username or userid has to be specified with service.
  • username [str] - Username of the profile on the social platform. Service has to be specified with username.
  • userid [str] - User ID of the profile on the social platform. Service has to be specified with userid.
  • url [str] - URL to the profile on the social platform. None of the other profile parameters can be specified with url.
• name [dict] - Name of the individual. Only queryable when provided in conjunction with location.
  • full [str] - Full name of the contact (givenName, familyName).
  • given [str] - The given name (first name) of the individual.
  • family [str] - The family name (last name) of the individual.
• location [dict] - Postal address of the individual. Only queryable when provided in conjunction with name.
  • addressLine1 [str] - The first address line of postal address.
  • addressLine2 [str] - The second address line of postal address.
  • city [str] - The city of postal address.
  • region [str] - The region of postal address.
  • regionCode [str] - The region code of postal address.
  • postalCode [str] - The postal code of postal address. Can accept Zip + 4 or Zip.
• maids list(str) - One or more Mobile Advertising IDs (MAIDs) for an individual, as a list.

Additional optional parameters that can be passed in query:

• confidence [str] (optional) - Acceptable values are 'LOW', 'MED', 'HIGH', and 'MAX'. If this parameter is not specified, the API defaults to the value 'HIGH'.

  The higher the confidence, the higher the likelihood that the data returned is accurate. If the confidence level of the data to be returned does not meet or exceed the parameter provided, then the result will not be a match. Generally, setting this value higher results in more accurate data, but fewer matches, while setting the value lower results in more matches and data, but lower quality and accuracy.

• infer [bool] (optional) - Flag for enabling or disabling inferences. If this parameter is not specified, the API defaults to True.

• dataFilter list(str) (optional) - A specific set of insight bundles can be provided in this parameter as a list, to tailor the result and only receive data back for specific Insights Bundles that are already enabled on your account.

• 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.

Valid combinations for profiles, name and location:

• profiles: A list of dictionaries of the above mentioned specification has to be provided to query by profiles. Only the below mentioned combinations are accepted:
  • service + username
  • service + userid
  • url
• location: A dictionary with above mentioned specification has to be provided, along with a valid name to query by location. Only the below mentioned combinations are accepted:
  • addressLine1 + city + region
  • addressLine1 + city + regionCode
  • addressLine1 + postalCode
• name: A dictionary with above mentioned specification has to be provided, along with a valid location to query by name. Only the below mentioned combinations are accepted:
  • full
  • given + family

Response

The response of enrich() method is a PersonEnrichResponse object of type fullcontact.response.person_response.PersonEnrichResponse. The responses are aligned with the Person Enrichment Response.

The response of enrich_async() method is a Future object of type concurrent.futures.Future. If successful, the Future.result() will return a PersonEnrichResponse.

PersonEnrichResponse

PersonEnrichResponse 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 Person summary extracted from raw response. This is the person response without the details in it.
• get_details() -> [dict] - Returns the details from the person summary as a dictionary.
• get_name() -> [dict] - Returns the name, if available in the response, as a dictionary.
• get_age() -> [dict] - Returns the age, if available in the response, as a dictionary.
• get_gender() -> [str] - Returns the gender, if available in the response, as a string.
• get_demographics() -> [dict] - Returns the demographics, if available in the response, as a dictionary.
• get_emails() -> [list(str)] - Returns the emails, if available in the response, as a list of strings.
• get_phones() -> [list(str)] - Returns the phones, if available in the response, as a list of strings.
• get_profiles() -> [list(dict)] - Returns the profiles, if available in the response, as a list of dictionaries.
• get_locations() -> [list(dict)] - Returns the locations, if available in the response, as a list of dictionaries.
• get_employment() -> [list(dict)] - Returns the employment details, if available in the response, as a list of dictionaries.
• get_photos() -> [list(dict)] - Returns the photos, if available in the response, as a list of dictionaries.
• get_education() -> [list(dict)] - Returns the education details, if available in the response, as a list of dictionaries.
• get_urls() -> [list(dict)] - Returns the URLs, if available in the response, as a list of dictionaries.
• get_interests() -> [list(dict)] - Returns the interests, if available in the response, as a list of dictionaries.
• get_household() -> [dict] - Returns the household details, if available in the response, as a dictionary.
• get_finance() -> [dict] - Returns the finance details, if available in the response, as a dictionary.
• get_census() -> [dict] - Returns the census details, if available in the response, as a dictionary.

Future

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

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 enrich() method, but works asynchronously using a concurrent.futures.thread.ThreadPoolExecutor.

• Parameters: Same as the parameters of enrich() method.
• Returns: Future object. Result is delivered through Future.result() method, once done.
• Return type: concurrent.futures.Future

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

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

• Parameters: Same as 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 search() method, but works asynchronously using a concurrent.futures.thread.ThreadPoolExecutor.

• Parameters: Same as the parameters of search() method.
• Returns: Future object. Result is delivered through Future.result() method, once done.
• Return type: concurrent.futures.Future

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