Skip to content

PersonClient

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

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.

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": "abc@xyz.com", "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

Examples

  • Initialization
import os
from fullcontact import PersonClient

person_client = PersonClient(os.environ.get('FULLCONTACT_API_KEY'))
  • Synchronous simple query
person_response = person_client.enrich(email="marquitaross006@gmail.com")

print(person_response.get_summary())
{
  "fullName": "Marquita H Ross",
  "ageRange": "37-47",
  "gender": "Female",
  "location": "San Francisco, California, United States",
  "title": "Senior Petroleum Manager",
  "organization": "Mostow Co.",
  "twitter": "https://twitter.com/marqross91",
  "linkedin": "https://www.linkedin.com/in/marquita-ross-5b6b72192",
  "facebook": null,
  "bio": "Senior Petroleum Manager at Mostow Co.",
  "avatar": "https://img.fullcontact.com/sandbox/1gagrO2K67_oc5DLG_siVCpYVE5UvCu2Z.png",
  "website": "http://marquitaas8.com/",
  "isSandboxProfile": true,
  "updated": "1970-01-01"
}
  • Synchronous multifield query
person_response = person_client.enrich(**{
  "emails": [
    "marquitaross006@gmail.com"
  ],
  "phones": [
    "+14105551773"
  ]
})

print(person_response.get_summary())
{
  "fullName": "Marquita H Ross",
  "ageRange": "37-47",
  "gender": "Female",
  "location": "San Francisco, California, United States",
  "title": "Senior Petroleum Manager",
  "organization": "Mostow Co.",
  "twitter": "https://twitter.com/marqross91",
  "linkedin": "https://www.linkedin.com/in/marquita-ross-5b6b72192",
  "facebook": null,
  "bio": "Senior Petroleum Manager at Mostow Co.",
  "avatar": "https://img.fullcontact.com/sandbox/1gagrO2K67_oc5DLG_siVCpYVE5UvCu2Z.png",
  "website": "http://marquitaas8.com/",
  "isSandboxProfile": true,
  "updated": "1970-01-01"
}
  • Synchronous query by name and address with insights bundle
query = {
  "name": {
    "given": "Marquita",
    "family": "Ross"
  },
  "location": {
    "addressLine1": "313 North Gainsway Street",
    "city": "San Francisco",
    "region": "California"
  }
}

person_response = person_client.enrich(dataAddon=["location"], **query)

print(person_response.get_summary())
{
  "fullName": "Marquita H Ross",
  "ageRange": "37-47",
  "gender": "Female",
  "location": "San Francisco, California, United States",
  "title": "Senior Petroleum Manager",
  "organization": "Mostow Co.",
  "twitter": "https://twitter.com/marqross91",
  "linkedin": "https://www.linkedin.com/in/marquita-ross-5b6b72192",
  "facebook": null,
  "bio": "Senior Petroleum Manager at Mostow Co.",
  "avatar": "https://img.fullcontact.com/sandbox/1gagrO2K67_oc5DLG_siVCpYVE5UvCu2Z.png",
  "website": "http://marquitaas8.com/",
  "isSandboxProfile": true,
  "updated": "1970-01-01"
}
  • Asynchronous queries
import concurrent.futures

from fullcontact.exceptions import FullContactException

queries = [
  {
    "email": "marquitaross006@gmail.com"
  },
  {
    "email": "ispangler@yandex.com",
    "phone": "+12075550145"
  },
  {
    "phone": "+14105551773"
  }
]

futures = [ person_client.enrich_async(query) for query in queries ]

for future in concurrent.futures.as_completed(futures):
  try:
    data = future.result()
  except FullContactException as fc_exception:
    print("FullContactException occurred: %s" % str(fc_exception))
  except Exception as other_exception:
    print("Some error occurred: %s" % str(other_exception))
Clone this wiki locally