Client library for FullContact V3 Enrich and Resolve APIs
Project description
FullContact Client
The official python client library for FullContact V3 API. This client provides an interface to perform Person Enrich, Company Enrich and Company Search operations.
FullContact API Documentation is available at: https://dashboard.fullcontact.com/api-ref
Table of contents
Requirements
This library requires Python 3.5 or above.
Adding To Your Project
To add FullContact Python Client library to your project, add the below line to your requirements.txt
file, or as a requirement in the setup.py
file.
python-fullcontact==2.0.0
Installation
It is recommended to install the FullContact python client library from PyPi using the below command.
pip install python-fullcontact
It is also possible to install the package from this repo, by running the below commands.
pip install git+https://github.com/fullcontact/fullcontact-python-client.git
Migrating from FullContact Client V1.0.0
This version of FullContact Client (V2.0.0) has significant changes in terms of design and features. Hence, it is not backward compatible with V1.0.0 library. However, migrating from the V1.0.0 client is very easy. In V1.0.0, there used to be different clients for different APIs (PersonClient, CompanyClient). However with V2.0.0, we have only 1 client, with different methods.
V1.0.0
from fullcontact import PersonClient, CompanyClient
person_client = PersonClient("<your_api_key>")
company_client = CompanyClient("<your_api_key>")
person_client.enrich(**query)
company_client.enrich(**query)
company_client.search(**query)
This would be changed as below in V2.0.0
V2.0.0
from fullcontact import FullContactClient
fullcontact_client = FullContactClient("<your_api_key>")
fullcontact_client.person.enrich(**query)
fullcontact_client.company.enrich(**query)
fullcontact_client.company.search(**query)
Usage
Importing the client
The client is available straight out of the package fullcontact
.
from fullcontact import FullContactClient
Basic Usage
To use the client library, you need to initialize the client using the API KEY that you have generated from FullContact Developer Dashboard.
Once initialized, the client provides the Enrich
and Resolve
capabilities of the V3 FullContact API.
from fullcontact import FullContactClient
fullcontact_client = FullContactClient("<your_api_key>")
# V3 Person Enrich
person_enrich_result = fullcontact_client.person.enrich(email="marquitaross006@gmail.com")
# V3 Company Enrich
company_enrich_result = fullcontact_client.company.enrich(domain="fullcontact.com")
# V3 Company Search
company_search_results = fullcontact_client.company.search(companyName="fullcontact")
# V3 Identity Map
identity_map_result = fullcontact_client.identity.map(email="marquitaross006@gmail.com", recordId="customer123")
# V3 Identity Resolve
identity_resolve_result = fullcontact_client.identity.resolve(recordId="customer123")
# V3 Identity Delete
identity_delete_result = fullcontact_client.identity.delete(recordId="customer123")
Client Configuration
The FullContact Client allows the configuration of additional headers and retry related values, through init parameters.
API Key
API Key is required to Authorize with FullContact API and hence, is a required parameter.
This is set using the api_key
init parameter for FullContactClient.
fullcontact_client = FullContactClient("<your_api_key>")
Headers
The headers Authorization
, Content-Type
and User-Agent
are added automatically and cannot be overridden. Hence, headers needs to be added only if any additional header needs to be passed to the API.
One useful situation for this is when you need to pass your Reporting-Key
.
The headers can be added by setting the headers
init parameter for FullContactClient.
additional_headers = {"Reporting-Key": "clientXYZ"}
fullcontact_client = FullContactClient(api_key="<your_api_key>", headers=additional_headers)
Retry
By default, the client retries a request if it receives a 429
or 503
status code. The default retry count is 1 and the backoff factor (base delay) for exponential backoff is 1 second.
Retry can by configured by setting the max_retry_count
, retry_status_codes
and base_delay
init parameters for FullContactClient.
If the value provided for max_retry_count
is greater than 5, it will be set to 5.
fullcontact_client = FullContactClient(api_key="<your_api_key>", max_retry_count=3, retry_status_codes=(429, 503, 413), base_delay=2.5)
FullContactClient
class: fullcontact.FullContactClient
Init parameters:
api_key
: str - (required)headers
: dict - [optional]max_retry_count
: int [default=5] - [optional]retry_status_codes
: List[int] [default=(429, 503)] - [optional]base_delay
: float [default=1.0] - [optional]
Person API
The client library provides methods to interact with V3 Person Enrich API through FullContactClient.person
object.
The V3 Person Enrich API can be called synchronously using enrich() and asynchronously using enrich_async().
Additional headers can be set on a per-request basis by setting the parameter headers
while calling enrich() or enrich_async().
Being a request level parameter, this can be used to override any header that has been set on the client level.
Person Enrichment API Documentation: https://dashboard.fullcontact.com/api-ref#person-enrichment
# Synchronous execution
enrich_response = fullcontact_client.person.enrich(email="marquitaross006@gmail.com")
print(enrich_response.get_name())
# Output: {'given': 'Marquita', 'family': 'Ross', 'full': 'Marquita H Ross'}
# Asynchronous execution
enrich_async_response = fullcontact_client.person.enrich_async(email="marquitaross006@gmail.com")
enrich_result = enrich_async_response.result()
print(enrich_result.get_name())
# Output: {'given': 'Marquita', 'family': 'Ross', 'full': 'Marquita H Ross'}
# Asynchronous execution using callback
def print_name_from_result(result: concurrent.Futures.Future):
enrich_result = result.result()
print(enrich_result.get_name())
fullcontact_client.person.enrich_async(email="marquitaross006@gmail.com").add_done_callback(print_name_from_result)
# Output: {'given': 'Marquita', 'family': 'Ross', 'full': 'Marquita H Ross'}
FullContactClient.person.enrich()
class: fullcontact.api.person_api.PersonApi
Parameters:
**query
: kwargs - (required)headers
: dict - [optional]
Supported fields for query:
email
: stremails
: List[str]phone
: strphones
: List[str]location
: dictaddressLine1
: straddressLine2
: strcity
: strregion
: strregionCode
: strpostalCode
: str
name
: dictfull
: strgiven
: strfamily
: str
profiles
: List[dict]service
: strusername
: struserid
: strurl
: str
maids
: List[str]recordId
: strpersonId
: strwebhookUrl
: strconfidence
: strdataFilter
: List[str]infer
: bool
Returns:
PersonEnrichResponse
class: fullcontact.response.person_response.PersonEnrichResponse
Instance variables
is_successful
: bool - Success flagresponse
: requests.Response - Raw requests.Response object
Methods:
json()
: dict - Response JSON as dictget_message()
: str - Response message or HTTP status messageget_headers()
: dict - Response headersget_summary()
: dict - Summary from Person Enrich Responseget_details()
: dict - Details from Person Enrich Responseget_name()
: dict - Name from Person Enrich Responseget_age()
: dict - Age from Person Enrich Responseget_gender()
: str - Gender from Person Enrich Responseget_demographics()
: dict - Demographics from Person Enrich Responseget_emails()
: List[str] - Emails from Person Enrich Responseget_phones()
: List[str] - Phones from Person Enrich Responseget_profiles()
: List[dict] - Profiles from Person Enrich Responseget_locations()
: List[dict] - Locations from Person Enrich Responseget_employment()
: List[dict] - Employments from Person Enrich Responseget_photos()
: List[dict] - Photos from Person Enrich Responseget_education()
: List[dict] - Educationget_urls()
: List[dict] - URLs from Person Enrich Responseget_interests()
: List[dict] - Interests from Person Enrich Responseget_household()
: dict - Household details from Person Enrich Responseget_finance()
: dict - Finance details from Person Enrich Responseget_census()
: dict - Census details from Person Enrich Responseget_identifiers()
: dict - Identifiers from Person Enrich Response
FullContactClient.person.enrich_async()
class: fullcontact.api.person_api.PersonApi Same as that of FullContactClient.person.enrich()
Returns:
Future[PersonEnrichResponse]
class: concurrent.Futures.Future
More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects
Useful Methods:
result()
: PersonEnrichResponse - PersonEnrichResponse object received once execution is completedadd_done_callback(fn)
: None - Add a callback function to be executed on successful execution.
Company API
The client library provides methods to interact with V3 Company Enrich and Search APIs through FullContactClient.company
object.
The V3 Company Enrich API can be called synchronously using enrich() and asynchronously using enrich_async().
Similarly, the V3 Company Search API can be called synchronously using search() and asynchronously using search_async().
Additional headers can be set on a per-request basis by setting the parameter headers
while calling enrich()), enrich_async(), search() or search_async().
Being a request level parameter, this can be used to override any header that has been set on the client level.
Company Enrichment API Documentation: https://dashboard.fullcontact.com/api-ref#company-enrichment
# Synchronous enrich execution
enrich_response = fullcontact_client.company.enrich(domain="fullcontact.com")
print(enrich_response.get_summary())
""" Output: {'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': None,
'bio': "Solving the world's contact information problem!",
'logo': 'https://img.fullcontact.com/static/7329d91237b7970b984d56c2497c80c0_7abd96cd75e5587b39b9f15dce07d7ebe8dc31accecf1b0f2a617ada34498633',
'website': 'https://www.fullcontact.com',
'founded': 2010,
'employees': 300,
'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-05-31'} """
# Synchronous search execution
search_response = fullcontact_client.company.search(companyName="fullcontact")
print(search_response.json()[0])
""" Output: {'lookupDomain': 'fullcontact.com',
'orgName': 'FullContact Inc',
'logo': 'https://d2ojpxxtu63wzl.cloudfront.net/v1/thumbnail?size=128&url=https://img.fullcontact.com/static/7329d91237b7970b984d56c2497c80c0_7abd96cd75e5587b39b9f15dce07d7ebe8dc31accecf1b0f2a617ada34498633',
'location': {'locality': 'Denver',
'region': {'name': 'CO'},
'country': {'name': 'USA'}}} """
# Asynchronous enrich execution
enrich_async_response = fullcontact_client.company.enrich_async(domain="fullcontact.com")
enrich_result = enrich_async_response.result()
print(enrich_result.get_summary())
# Asynchronous search execution
search_async_response = fullcontact_client.company.search_async(companyName="fullcontact")
search_result = search_async_response.result()
print(search_result.json()[0])
FullContactClient.company.enrich()
class: fullcontact.api.company_api.CompanyApi
Parameters:
**query
: kwargs - (required)headers
: dict - [optional]
Supported fields for query:
domain
: strwebhookUrl
: str
Returns:
CompanyEnrichResponse
class: fullcontact.response.company_response.CompanyEnrichResponse
Instance variables
is_successful
: bool - Success flagresponse
: requests.Response - Raw requests.Response object
Methods:
json()
: dict - Response JSON as dictget_message()
: str - Response message or HTTP status messageget_headers()
: dict - Response headersget_summary()
: dict - Summary from Company Enrich Responseget_details()
: dict - Details from Company Enrich Response
FullContactClient.company.enrich_async()
class: fullcontact.api.company_api.CompanyClient
Parameters:
Same as that of FullContactClient.company.enrich()
Returns:
Future[CompanyEnrichResponse]
class: concurrent.Futures.Future
More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects
Useful Methods:
result()
: CompanyEnrichResponse - CompanyEnrichResponse object received once execution is completedadd_done_callback(fn)
: None - Add a callback function to be executed on successful execution.
FullContactClient.company.search()
class: fullcontact.api.company_api.CompanyApi
Parameters:
**query
: kwargs - (required)headers
: dict - [optional]
Supported fields for query:
companyName
: strsort
: strlocation
: strlocality
: strregion
: strcountry
: strwebhookUrl
: str
Returns:
CompanySearchResponse
class: fullcontact.response.company_response.CompanySearchResponse
Instance variables
is_successful
: bool - Success flagresponse
: requests.Response - Raw requests.Response object
Methods:
json()
: dict - Response JSON as dictget_message()
: str - Response message or HTTP status messageget_headers()
: dict - Response headers
FullContactClient.company.search_async()
class: fullcontact.api.company_api.CompanyClient
Parameters:
Same as that of FullContactClient.company.search()
Returns:
Future[CompanySearchResponse]
class: concurrent.Futures.Future
More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects
Useful Methods:
result()
: CompanySearchResponse - CompanySearchResponse object received once execution is completedadd_done_callback(fn)
: None - Add a callback function to be executed on successful execution.
Resolve API
The client library provides methods to interact with V3 Resolve API (identity.map
, identity.resolve
and identity.delete
endpoints) through FullContactClient.identity
object.
The V3 Resolve API can be accessed using the methods map(), resolve() and delete(), respectively.
These APIs can be accessed using the async version these functions, map_async(), resolve_async() and delete_async().
Additional headers can be set on a per-request basis by setting the parameter headers
while calling these methods.
Being a request level parameter, this can be used to override any header that has been set on the client level.
Resolve API Documentation: https://dashboard.fullcontact.com/api-ref#resolve-2
# Synchronous map execution
map_response = fullcontact_client.identity.map(email="marquitaross006@gmail.com", recordId="customer123")
print(map_response.get_recordIds())
# Output: ['customer123']
# Synchronous resolve execution
resolve_response = fullcontact_client.identity.resolve(email="marquitaross006@gmail.com")
print(resolve_response.get_recordIds())
# Output: ['customer123']
# Synchronous delete execution
delete_response = fullcontact_client.identity.delete(recordId="customer123")
print(delete_response.is_successful)
# Output: True
# Asynchronous map execution
map_async_response = fullcontact_client.identity.map_async(email="marquitaross006@gmail.com", recordId="customer123")
map_response = map_async_response.result()
print(map_response.get_recordIds())
# Output: ['customer123']
# Asynchronous resolve execution
resolve_async_response = fullcontact_client.identity.resolve_async(email="marquitaross006@gmail.com")
resolve_response = resolve_async_response.result()
print(resolve_response.get_recordIds())
# Output: ['customer123']
# Asynchronous delete execution
delete_async_response = fullcontact_client.identity.delete_async(recordId="customer123")
delete_response = delete_async_response.result()
print(delete_response.is_successful)
# Output: True
FullContactClient.identity.map()
class: fullcontact.api.resolve_api.ResolveClient
Parameters:
**fields
: kwargs - (required)headers
: dict - [optional]
Supported fields for mapping:
email
: stremails
: List[str]phone
: strphones
: List[str]location
: dictaddressLine1
: straddressLine2
: strcity
: strregion
: strregionCode
: strpostalCode
: str
name
: dictfull
: strgiven
: strfamily
: str
profiles
: List[dict]service
: strusername
: struserid
: strurl
: str
maids
: List[str]recordId
: str - (required)
Returns:
IdentityMapResponse
class: fullcontact.response.resolve_response.IdentityMapResponse
Instance variables
is_successful
: bool - Success flagresponse
: requests.Response - Raw requests.Response object
Methods:
json()
: dict - Response JSON as dictget_message()
: str - Response message or HTTP status messageget_headers()
: dict - Response headersget_recordIds()
: List[str] - List of recordIds from Map response
FullContactClient.identity.map_async()
class: fullcontact.api.resolve_api.ResolveClient
Parameters:
Same as that of FullContactClient.identity.map()
Returns:
Future[IdentityMapResponse]
class: concurrent.Futures.Future
More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects
Useful Methods:
result()
: IdentityMapResponse - IdentityMapResponse object received once execution is completedadd_done_callback(fn)
: None - Add a callback function to be executed on successful execution.
FullContactClient.identity.resolve()
class: fullcontact.api.resolve_api.ResolveApi
Parameters:
**fields
: kwargs - (required)headers
: dict - [optional]
Supported fields for mapping: Same as that of FullContactClient.identity.map(), but with one more extra field
personId
: str
Note: recordId and personId cannot be used together to resolve. Only one of these fields can be used in a request.
Returns:
IdentityResolveResponse
class: fullcontact.response.resolve_response.IdentityResolveResponse
Instance variables
is_successful
: bool - Success flagresponse
: requests.Response - Raw requests.Response object
Methods:
json()
: dict - Response JSON as dictget_message()
: str - Response message or HTTP status messageget_headers()
: dict - Response headersget_recordIds()
: List[str] - List of recordIds from Resolve responseget_personIds()
: List[str] - List of personIds from Resolve response
FullContactClient.identity.resolve_async()
class: fullcontact.api.resolve_api.ResolveApi
Parameters:
Same as that of FullContactClient.identity.resolve()
Returns:
Future[IdentityResolveResponse]
class: concurrent.Futures.Future
More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects
Useful Methods:
result()
: IdentityResolveResponse - IdentityResolveResponse object received once execution is completedadd_done_callback(fn)
: None - Add a callback function to be executed on successful execution.
FullContactClient.identity.delete()
class: fullcontact.api.resolve_api.ResolveApi
Parameters:
recordId
: str - (required)headers
: dict - [optional]
Returns:
IdentityDeleteResponse
class: fullcontact.response.resolve_response.IdentityDeleteResponse
Instance variables
is_successful
: bool - Success flagresponse
: requests.Response - Raw requests.Response object
Methods:
json()
: dict - Response JSON as dict. Empty dict will be returned on successful delete.get_message()
: str - Response message or HTTP status messageget_headers()
: dict - Response headers
FullContactClient.identity.delete_async()
class: fullcontact.api.resolve_api.ResolveApi
Parameters:
Same as that of FullContactClient.identity.delete()
Returns:
Future[IdentityDeleteResponse]
class: concurrent.Futures.Future
More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects
Useful Methods:
result()
: IdentityDeleteResponse - IdentityDeleteResponse object received once execution is completedadd_done_callback(fn)
: None - Add a callback function to be executed on successful execution.
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-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c1999697a3f1e9a91ed50ed96b96c8cb6a96e112b90ce64da15595c0032721fb |
|
MD5 | c4d13cd7ae6362673a834b1ab04a3d4b |
|
BLAKE2b-256 | fa31ab4ab4248ea58edffcc0a5ff9289bf1f80317d61a148cae5ce4f2d30e631 |