A simple Fullcontact API client library
Project description
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
andContent-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 throughFuture.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": "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 byprofiles
. 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 validname
to query bylocation
. 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 validlocation
to query byname
. 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 inquery
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 throughFuture.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 inquery
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 throughFuture.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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python_fullcontact-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4a9c865fb18a17d745c2ff7afdb12a1403c7b08fe49bdcbb932b5a0061f12ad2 |
|
MD5 | 507291679fe205b6a5ae1bbea0df60d7 |
|
BLAKE2b-256 | 5f1bea2b1c1449527ddfe41e12b536a8429743e44328e61ac5d77f60e66ea80b |