python-fullcontact 4.0.0

Client library for FullContact V3 Enrich and Resolve APIs

FullContact Client

The official python client library for FullContact V3 API. This client provides an interface to interact with Enrich, Resolve, Tags, Audience, Verify and Permission APIs. FullContact API Documentation is available at: https://platform.fullcontact.com/docs

Table of contents

• Requirements
• Adding To Your Project
• Installation
• Migrating from FullContact Client V1.0.0
• Usage
  • Importing the client
  • Basic Usage
  • Client Configuration
  • Person API
    • enrich()
    • enrich_async()
  • Company API
    • enrich()
    • enrich_async
  • Resolve API
    • map()
    • map_async()
    • resolve()
    • resolve_async()
    • mapResolve()
    • mapResolve_async()
    • delete()
    • delete_async()
  • Tags API
    • get()
    • get_async()
    • create()
    • create_async()
    • delete()
    • delete_async()
  • Audience
    • create()
    • create_async()
    • download()
    • download_async()
  • Permission
    • create
    • delete
    • find
    • current
    • verify
    • permission-async
  • Verify
    • match
    • match_async
    • signals
    • signals_async
    • activity
    • activity_async

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==4.0.0

Installation

It is recommended to install the FullContact python client library from PyPi using the below command.

pip install python-fullcontact

If you'd like to install the development version (with pytest), run instead:

pip install 'python-fullcontact[develop]'

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)

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)

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 Platform. 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>")

# Person Enrich
person_enrich_result = fullcontact_client.person.enrich(email="[e-mail]")

# Company Enrich
company_enrich_result = fullcontact_client.company.enrich(domain="fullcontact.com")

# Identity Map
identity_map_result = fullcontact_client.identity.map(email="[e-mail]", recordId="customer123")

# Identity Resolve
identity_resolve_result = fullcontact_client.identity.resolve(recordId="customer123")

# Identity Map Resolve
identity_mapResolve_result = fullcontact_client.identity.mapResolve(email="[e-mail]", recordId="customer123", generatePid=True)

# Identity Delete
identity_delete_result = fullcontact_client.identity.delete(recordId="customer123")

# Tags Get
tags_get_result = fullcontact_client.tags.get(recordId="customer123")

# Tags Create
tags_create_result = fullcontact_client.tags.create(recordId="customer123",
                                                    tags={"tag1": "value1", "tag2": ["value2", "value3"]})

# Tags Delete
tags_delete_result = fullcontact_client.tags.create(recordId="customer123",
                                                    tags={"tag2": "value2"})

# Audience Create
audience_create_result = fullcontact_client.audience.create(webhookUrl="http://your_webhook_url/",
                                                            tags={"tag1": "value1", "tag2": "value2"})

# Audience Download
audience_download_result = fullcontact_client.audience.download(requestId="<your_requestId>")
audience_download_result.write_to_file("<output_file_path>")

# Permission Create
permission_create_result = fullcontact_client.permission.create(
                                            query={"email": "[e-mail]"},
                                            consentPurposes=[
                                                {
                                                    "purposeId": 2,
                                                    "channel": ["web","phone","mobile","offline","email"],
                                                    "ttl": 1095,
                                                    "enabled": True
                                                }
                                            ],
                                            locale="US",
                                            language="en",
                                            collectionMethod="cookie",
                                            collectionLocation="US",
                                            policyUrl="https://www.fullcontact-test.com/services-privacy-policy/",
                                            termsService="https://www.fullcontact-test.com/content-policy/")  

# Permission Delete
permission_delete_result = fullcontact_client.permission.delete({"email": "[e-mail]"})
# Permission Find
permission_find_result = fullcontact_client.permission.find(email="[e-mail]")

# Permission Current
permission_current_result = fullcontact_client.permission.current(email="[e-mail]")

# Permission Verify
permission_verify_result = fullcontact_client.permission.verify(query={"email": "[e-mail]"},
                                                                purposeId=6, 
                                                                channel="web")
# Verify Match
verify_match_result = fullcontact_client.verify.match(email="[e-mail]")

# Verify Signals
verify_signals_result = fullcontact_client.verify.signals(email="[e-mail]")

# Verify Activity
verify_activity_result = fullcontact_client.verify.activity(email="[e-mail]")

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)

MultiFieldRequest

Ability to match on one or many input fields. The more contact data inputs you can provide, the better. By providing more contact inputs, the more accurate and precise we can get with our identity resolution capabilities.

• email: str
• emails: List[str]
• phone: str
• phones: List[str]
• placekey: str
• location: dict
  • addressLine1: str
  • addressLine2: str
  • city: str
  • region: str
  • regionCode: str
  • postalCode: str
• name: dict
  • full: str
  • given: str
  • family: str
• profiles: List[dict]
  • service: str
  • username: str
  • userid: str
  • url: str
• maids: List[str]
• recordId: str
• personId: str
• li_nonid: str
• partnerId: str
• panoramaId: str

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://platform.fullcontact.com/docs/apis/enrich/multi-field-request

# Synchronous execution
enrich_response = fullcontact_client.person.enrich(email="[e-mail]")
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="[e-mail]")
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="[e-mail]").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]

query takes in MultiFieldReq. Other supported fields for query:

• webhookUrl: str
• confidence: str
• dataFilter: List[str]
• infer: bool
• maxMaids: int

Returns:

PersonEnrichResponse

class: fullcontact.response.person_response.PersonEnrichResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_summary(): dict - Summary from Person Enrich Response
• get_details(): dict - Details from Person Enrich Response
• get_name(): dict - Name from Person Enrich Response
• get_age(): dict - Age from Person Enrich Response
• get_gender(): str - Gender from Person Enrich Response
• get_demographics(): dict - Demographics from Person Enrich Response
• get_emails(): List[str] - Emails from Person Enrich Response
• get_phones(): List[str] - Phones from Person Enrich Response
• get_profiles(): List[dict] - Profiles from Person Enrich Response
• get_locations(): List[dict] - Locations from Person Enrich Response
• get_employment(): List[dict] - Employments from Person Enrich Response
• get_photos(): List[dict] - Photos from Person Enrich Response
• get_education(): List[dict] - Education
• get_urls(): List[dict] - URLs from Person Enrich Response
• get_interests(): List[dict] - Interests from Person Enrich Response
• get_household(): dict - Household details from Person Enrich Response
• get_finance(): dict - Finance details from Person Enrich Response
• get_census(): dict - Census details from Person Enrich Response
• get_identifiers(): dict - Identifiers from Person Enrich Response
• get_extended(): dict - All Extended data

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 completed
• add_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 API through FullContactClient.company object. The V3 Company 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())

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://platform.fullcontact.com/docs/apis/enrich/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',
 'updated': '2020-05-31'} """

# 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())

FullContactClient.company.enrich()

class: fullcontact.api.company_api.CompanyApi

Parameters:

• **query: kwargs - (required)
• headers: dict - [optional]

Supported fields for query:

• domain: str
• webhookUrl: str

Returns:

CompanyEnrichResponse

class: fullcontact.response.company_response.CompanyEnrichResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_summary(): dict - Summary from Company Enrich Response
• get_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 completed
• add_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, identity.mapResolve, and identity.delete endpoints) through FullContactClient.identity object. The V3 Resolve API can be accessed using the methods map(), resolve(), mapResolve(), and delete(), respectively. These APIs can be accessed using the async version these functions, map_async() , resolve_async(), mapResolve_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://platform.fullcontact.com/docs/apis/resolve/multi-field-request

# Synchronous map execution
map_response = fullcontact_client.identity.map(email="[e-mail]", recordId="customer123")
print(map_response.get_recordIds())
# Output: ['customer123']

# Synchronous resolve execution
resolve_response = fullcontact_client.identity.resolve(email="[e-mail]")
print(resolve_response.get_recordIds())
# Output: ['customer123']

# Synchronous mapResolve execution
mapResolve_response = fullcontact_client.identity.mapResolve(email="[e-mail]", recordId="customer123")
print(mapResolve_response.get_recordIds())
print(mapResolve_response.get_personIds())
# Output: 
# ['customer123']
# ['OdcKOTonyt5diGjjf-CXHrn84Zr_PcPGmqj1NYSiCR_U-J7v']

# 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="[e-mail]", 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="[e-mail]")
resolve_response = resolve_async_response.result()
print(resolve_response.get_recordIds())
# Output: ['customer123']

# Asynchronous mapResolve execution
mapResolve_async_response = fullcontact_client.identity.mapResolve_async(email="[e-mail]", recordId="customer123")
mapResolve_response = mapResolve_async_response.result()
print(mapResolve_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]

fields takes in MultiFieldReq. Other supported fields for mapping:

• tags: List[str]
• generatePid: bool

Returns:

IdentityMapResponse

class: fullcontact.response.resolve_response.IdentityMapResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_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 completed
• add_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)
• include_tags: `bool - [optional]

  If include_tags is set to True, the response will include tags in the response.

• 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 flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_recordIds(): List[str] - List of recordIds from Resolve response
• get_personIds(): List[str] - List of personIds from Resolve response
• get_partnerIds(): List[str] - List of partnerIds from Resolve response
• get_tags(): Dict - A dict of tags, if include_tags was set to True in the request

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 completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

FullContactClient.identity.mapResolve()

class: fullcontact.api.resolve_api.ResolveClient

Parameters:

• **fields: kwargs - (required)
• headers: dict - [optional]

fields takes in MultiFieldReq. Other supported fields for mapping:

• tags: List[str]
• generatePid: bool

Returns:

IdentityResolveResponse

class: fullcontact.response.resolve_response.IdentityResolveResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_recordIds(): List[str] - List of recordIds from Map response

FullContactClient.identity.mapResolve_async()

class: fullcontact.api.resolve_api.ResolveClient

Parameters:

Same as that of FullContactClient.identity.mapResolve()

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 completed
• add_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 flag
• response: 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 message
• get_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 completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

Tags API

The client library provides methods to interact with Customer Tags API (tags.get, tags.create and tags.delete endpoints) through FullContactClient.tags object. The Tags API can be accessed using the methods get(), create() and delete(), respectively. These APIs can be accessed using the async version these functions, get_async(), create_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.

Tags API Documentation: https://platform.fullcontact.com/docs/apis/resolve/customer-tags

# Synchronous create execution
create_response = fullcontact_client.tags.create(recordId="customer123",
                                                 tags={"segment": "highspender"})
print(create_response.json())
# Output: {'recordId': 'customer123', 'tags': [{'key': 'segment', 'value': 'highspender'}]}

# Synchronous get execution
get_response = fullcontact_client.tags.get(recordId="customer123")
print(get_response.get_tags())
# Output: {'segment': ['highspender']}

# Synchronous delete execution
delete_response = fullcontact_client.tags.delete(recordId="customer123",
                                                 tags={"segment": "highspender"})
print(delete_response.get_status_code())
# Output: 204

# Asynchronous create execution
create_async_response = fullcontact_client.tags.create_async(recordId="customer123",
                                                             tags={"segment": "highspender"})
create_response = create_async_response.result()
print(create_response.json())
# Output: {'recordId': 'customer123', 'tags': [{'key': 'segment', 'value': 'highspender'}]}

# Asynchronous get execution
get_async_response = fullcontact_client.tags.get_async(recordId="customer123")
get_response = get_async_response.result()
print(get_response.get_tags())
# Output: {'segment': ['highspender']}

# Asynchronous delete execution
delete_async_response = fullcontact_client.tags.delete_async(recordId="customer123",
                                                             tags={"segment": "highspender"})
delete_response = delete_async_response.result()
print(delete_response.get_status_code())
# Output: 204

FullContactClient.tags.create()

class: fullcontact.api.tags_api.TagsApi

Parameters:

• recordId: str - (required)
• tags: dict - (required)

  Tags dict has to be in the format {tag1_key: tag1_value, tag2_key: [tag2_value1, tag2_value2], ...}. Tag value can be a string or a list of strings to support multiple values.

• headers: dict - [optional]

Returns:

TagsCreateResponse

class: fullcontact.response.tags_response.TagsCreateResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers

FullContactClient.tags.create_async()

class: fullcontact.api.tags_api.TagsApi

Parameters:

Same as that of FullContactClient.tags.create()

Returns:

Future[TagsCreateResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): TagsCreateResponse - TagsCreateResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

FullContactClient.tags.get()

class: fullcontact.api.tags_api.TagsApi

Parameters:

• **identifiers: kwargs - (required)
• headers: dict - [optional]

Supported identifiers to get tags:

• recordId: str
• partnerId: str

Returns:

TagsGetResponse

class: fullcontact.response.tags_response.TagsGetResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_tags(): dict - Tags from the response in format {tag1_key: tag1_value, tag2_key, tag2_value, ...}
• get_recordId(): str - recordId from the response
• get_partnerId(): str - partnerId from the response

FullContactClient.tags.get_async()

class: fullcontact.api.tags_api.TagsApi

Parameters:

Same as that of FullContactClient.tags.get()

Returns:

Future[TagsGetResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): TagsGetResponse - TagsGetResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

FullContactClient.tags.delete()

class: fullcontact.api.tags_api.TagsApi

Parameters:

• recordId: str - (required)
• tags: dict - (required)

  Tags dict has to be in the format {tag1_key: tag1_value, tag2_key: tag2_value, ...}

• headers: dict - [optional]

Returns:

TagsDeleteResponse

class: fullcontact.response.tags_response.TagsDeleteResponse

Instance variables

• is_successful: bool - Success flag
• response: 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 message
• get_headers(): dict - Response headers

FullContactClient.tags.delete_async()

class: fullcontact.api.tags_api.TagsApi

Parameters:

Same as that of FullContactClient.tags.delete()

Returns:

Future[TagsDeleteResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): TagsDeleteResponse - TagsDeleteResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

Audience API

The client library provides methods to interact with Audience Tags API (audience.create and audience.download endpoints) through FullContactClient.audience object. The Audience API can be accessed using the methods create() and download(), respectively. These APIs can be accessed using the async version these functions, create_async() and download_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.

Tags API Documentation: https://platform.fullcontact.com/docs/apis/resolve/customer-tags

# Synchronous create execution
create_response = fullcontact_client.audience.create(webhookUrl="http://your_webhookUrl/",
                                                     tags={"segment": "highspender"})
print(create_response.json())
# Output: {'requestId': 'c7273de7-e717-4cab-9fe0-213ab3796636'}

# Synchronous download execution
download_response = fullcontact_client.audience.download(requestId="c7273de7-e717-4cab-9fe0-213ab3796636")
download_response.write_to_file("/path/to/output_file.json.gz")
print(download_response.get_status_code())
# Output: 200

# Asynchronous create execution
create_async_response = fullcontact_client.audience.create(webhookUrl="http://your_webhookUrl/",
                                                           tags={"segment": "highspender"})
create_response = create_async_response.result()
print(create_response.json())
# Output: {'requestId': 'c7273de7-e717-4cab-9fe0-213ab3796636'}

# Asynchronous download execution
download_async_response = fullcontact_client.audience.download_async(requestId="c7273de7-e717-4cab-9fe0-213ab3796636")
download_response = download_async_response.result()
download_response.write_to_file("/path/to/output_file.json.gz")
print(download_response.get_status_code())
# Output: 200

FullContactClient.audience.create()

class: fullcontact.api.tags_api.AudienceApi

Parameters:

• webhookUrl: str - (required)
• tags: dict - (required)

  Tags dict has to be in the format {tag1_key: tag1_value, tag2_key: tag2_value, ...}

• headers: dict - [optional]

Returns:

AudienceCreateResponse

class: fullcontact.response.audience_response.AudienceCreateResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_requestId(): str - requestId created for the request

FullContactClient.audience.create_async()

class: fullcontact.api.audience_api.AudienceApi

Parameters:

Same as that of FullContactClient.audience.create()

Returns:

Future[AudienceCreateResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): AudienceCreateResponse - AudienceCreateResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

FullContactClient.audience.download()

class: fullcontact.api.audience_api.AudienceApi

Parameters:

• requestId: str - (required)
• headers: dict - [optional]

Returns:

AudienceDownloadResponse

class: fullcontact.response.audience_response.AudienceDownloadResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• write_to_file(file): bool - Writes the downloaded file contents to the input file/fileObj
  • Param file : str/FileObject - It can the path to a file as string or a bytes writable file object. The file will be of format .json.gz if the download was successful. This can be confirmed using the is_successful flag.

  An easy way to create a bytes writable file object is by using io.BytesIO

FullContactClient.audience.download_async()

class: fullcontact.api.audience_api.AudienceApi

Parameters:

Same as that of FullContactClient.audience.download()

Returns:

Future[AudienceDownloadResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): AudienceDownloadResponse - AudienceDownloadResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

Permission API

The client library provides methods to interact with Permission through FullContactClient.permission object. 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.

Permission APIs Documentation: https://platform.fullcontact.com/docs/apis/permission/introduction

class: fullcontact.api.permission_api.PermissionApi

# Synchronous create execution
permission_create_response = fullcontact_client.permission.create(
                            query={"email": "[e-mail]"},
                            consentPurposes=[
                                {
                                    "purposeId": 2,
                                    "channel": ["web","phone","mobile","offline","email"],
                                    "ttl": 1095,
                                    "enabled": True
                                },
                                {
                                    "purposeId": 5,
                                    "channel": ["web","phone","mobile","offline","email"],
                                    "ttl": 1095,
                                    "enabled": True
                                }
                            ],
                            locale="US",
                            language="en",
                            collectionMethod="cookie",
                            collectionLocation="US",
                            policyUrl="https://www.fullcontact-test.com/services-privacy-policy/",
                            termsService="https://www.fullcontact-test.com/content-policy/"
                            )
print(permission_create_response.get_status_code())
# Output: 202

# Synchronous delete execution
permission_delete_response = fullcontact_client.permission.delete(query={"email": "[e-mail]"})
print(permission_delete_response.get_status_code())
# Output: 202

# Synchronous find execution
permission_find_response = fullcontact_client.permission.find(query={"email": "[e-mail]"})
print(permission_find_response.json())
'''
Output:
[
    {
        "permissionType": "create",
        "permissionId": "0089ced6-eaa8-4ac4-a6b2-de9d16928461",
        "consentPurposes": [
            {
                "ttl": null,
                "enabled": True,
                "channel": "web",
                "purposeId": 6,
                "purposeName": "Content selection, delivery & reporting",
                "timestamp": 1614855618604
            }
        ],
        "locale": "US",
        "ipAddress": "127.0.0.1",
        "language": "en",
        "collectionMethod": "cookie",
        "collectionLocation": "ae",
        "policyUrl": "https://www.fullcontact-test.com/services-privacy-policy/",
        "termsService": "https://www.fullcontact-test.com/content-policy/",
        "timestamp": None,
        "created": 1614855618604
    },
    {
        "permissionType": "delete",
        "permissionId": "0089ced6-eaa8-4ac4-a6b2-de9d169284rt4",
        "consentPurposes": [
            {
                "ttl": null,
                "enabled": True,
                "channel": "web",
                "purposeId": 2,
                "purposeName": "Content selection, delivery & reporting",
                "timestamp": 1614855618607
            }
        ],
        "locale": "US",
        "ipAddress": "127.0.0.1",
        "language": "en",
        "collectionMethod": "cookie",
        "collectionLocation": "ae",
        "policyUrl": "https://www.fullcontact-test.com/services-privacy-policy/",
        "termsService": "https://www.fullcontact-test.com/content-policy/",
        "timestamp": None,
        "created": 1614855618607
    }
]
'''
# Synchronous Current execution
permission_current_response = fullcontact_client.permission.current(query={"email": "[e-mail]"})
print(permission_current_response.json())
'''
Output:
{
    "3": {
        "offline": {
            "ttl": 1095,
            "enabled": True,
            "channel": "offline",
            "purposeId": 3,
            "purposeName": "Personalized Content Profile",
            "timestamp": 1614837134541
        },
        "phone": {
            "ttl": 1095,
            "enabled": True,
            "channel": "phone",
            "purposeId": 3,
            "purposeName": "Personalized Content Profile",
            "timestamp": 1614837134541
        },
        "mobile": {
            "ttl": 1095,
            "enabled": True,
            "channel": "mobile",
            "purposeId": 3,
            "purposeName": "Personalized Content Profile",
            "timestamp": 1614837134541
        },
        "email": {
            "ttl": 1095,
            "enabled": True,
            "channel": "email",
            "purposeId": 3,
            "purposeName": "Personalized Content Profile",
            "timestamp": 1614837134541
        }
    },
    "6": {
        "web": {
            "ttl": null,
            "enabled": True,
            "channel": "web",
            "purposeId": 6,
            "purposeName": "Content selection, delivery & reporting",
            "timestamp": 1614856047618
        }
    }
}
'''
# Synchronous Verify execution
permission_verify_response = fullcontact_client.permission.verify(query={"email": "[e-mail]"},
                                                                purposeId=6, 
                                                                channel="web")
print(permission_verify_response.json())
'''
Output:
{
    "ttl": 1024,
    "enabled": true,
    "channel": "web",
    "purposeId": 6,
    "purposeName": "Content selection, delivery & reporting",
    "timestamp": 1614856047613
}
'''

FullContactClient.permission.create()

class: fullcontact.schema.permission_schema.PermissionCreateRequestSchema

Parameters:

• **query: kwargs - [required]
• headers: dict - [optional]

Supported fields in query:

• query: MultifieldReq - [required]
• consentPurposes: List[PurposeRequestSchema] - [required]
• locale: str
• ipAddress: str
• language: str
• collectionMethod: str - [required]
• collectionLocation: str - [required]
• policyUrl: str - [required]
• termsService: str - [required]
• tcf: str
• timestamp: int

PurposeRequestSchema

• purposeId: int - [required]
• channel: List[str]
• ttl: int
• enabled: bool - [required]

Returns:

class: fullcontact.response.permission_response.PermissionCreateResponse

A basic API response with response code as 202 if successful.

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers

FullContactClient.permission.delete()

class: fullcontact.schema.permission_schema.PermissionDeleteRequestSchema

Parameters:

• **query: kwargs - [required]
• headers: dict - [optional]

query takes a MultiFieldReq

Returns:

class: fullcontact.response.permission_response.PermissionDeleteResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers

FullContactClient.permission.find()

class: fullcontact.schema.permission_schema.PermissionFindRequestSchema

Parameters:

• **query: kwargs - [required]
• headers: dict - [optional]

query takes a MultiFieldReq

Returns:

class: fullcontact.response.permission_response.PermissionFindResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers

FullContactClient.permission.current()

class: fullcontact.schema.permission_schema.PermissionCurrentRequestSchema

Parameters:

same as that of FullContactClient.permission.find()

Returns:

class: fullcontact.response.permission_response.PermissionCurrentResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_consent_for_purposeId(self, purposeId: int): dict - of Consent set for the purposeId

FullContactClient.permission.verify()

class: fullcontact.schema.permission_schema.PermissionVerifyRequestSchema

Parameters:

• **query: kwargs - [required]
• headers: dict - [optional]

Supported fields in query:

• query: MultifieldReq - [required]
• purposeId: int - [required]
• channel: str - [required]

Returns:

class: fullcontact.response.permission_response.PermissionVerifyResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers

Permission APIs Asynchronous methods

Client Library also support corresponding async methods for Permission APIs such as:

• permission.create_async()
• permission.delete_async()
• permission.find_async()
• permission.current_async()
• permission.verify_async()

All these takes same parameters as their synchronous counterparts but return a Future instead.

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Verify API

The client library provides methods to interact with V3 Verfiy API (verify.match, verify.signals and verify.activity endpoints) through FullContactClient.verify object. The V3 Verify API can be accessed using the methods match(), signals() and activity(), respectively. These APIs can be accessed using the async version these functions, match_async(), signals_async() and activity_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.

Verify API Documentation: https://docs.fullcontact.com/docs/verify-overview

# Synchronous match execution
match_response = fullcontact_client.verify.match(email="[e-mail]")
print(match_response.json())
# Output: {'email': True}

# Synchronous signals execution
signals_response = fullcontact_client.verify.signals(email="[e-mail]")
print(signals_response.json())
'''
Output: 
{ 'personIds': ['L0yG2Mp8Z4TVHxJK92GAxjWsTX6lrSfMBsQKvRsy5NzKnTm6'], 
  'maids': [{'id': '0N3ZIUBF-RPCI-GO59-O29M-S3I3U0A8I9WUN', 'type': 'idfa', 'firstSeenMs': 0, 'lastSeenMs': 0, 'observations': 1, 'confidence': 1.0}], 
  'name': {'givenName': 'Marquita', 'familyName': 'Ross'}, 
  'nonIds': [{'id': '0C-83f57c786a0b_-4a39efab23731c7EBC', 'firstSeenMs': 0, 'lastSeenMs': 0, 'observations': 1, 'confidence': 1.0}], 
  'socialProfiles': {'twitterUrl': 'https://twitter.com/marqross91', 'linkedInUrl': 'https://www.linkedin.com/in/marquita-ross-5b6b72192'}, 
  'demographics': {'age': 42, 'ageRange': '40-49', 'gender': 'Female'}, 
  'employment': {'current': True, 'company': 'Mostow Co.', 'title': 'Senior Petroleum Manager'}
}
'''

# Synchronous activity execution
activity_response = fullcontact_client.verify.activity(email="[e-mail]")
print(activity_response.json())
# Output: {'emails': 0.03}

# Asynchronous match execution
match_async_response = fullcontact_client.verify.match_async(email="[e-mail]")
match_response = match_async_response.result()
print(match_response.json())
# Output: {'email': True}

# Asynchronous signals execution
signals_async_response = fullcontact_client.verify.signals_async(email="[e-mail]")
signals_response = signals_async_response.result()
print(signals_response.json())
'''
Output: 
{ 'personIds': ['L0yG2Mp8Z4TVHxJK92GAxjWsTX6lrSfMBsQKvRsy5NzKnTm6'], 
  'maids': [{'id': '0N3ZIUBF-RPCI-GO59-O29M-S3I3U0A8I9WUN', 'type': 'idfa', 'firstSeenMs': 0, 'lastSeenMs': 0, 'observations': 1, 'confidence': 1.0}], 
  'name': {'givenName': 'Marquita', 'familyName': 'Ross'}, 
  'nonIds': [{'id': '0C-83f57c786a0b_-4a39efab23731c7EBC', 'firstSeenMs': 0, 'lastSeenMs': 0, 'observations': 1, 'confidence': 1.0}], 
  'socialProfiles': {'twitterUrl': 'https://twitter.com/marqross91', 'linkedInUrl': 'https://www.linkedin.com/in/marquita-ross-5b6b72192'}, 
  'demographics': {'age': 42, 'ageRange': '40-49', 'gender': 'Female'}, 
  'employment': {'current': True, 'company': 'Mostow Co.', 'title': 'Senior Petroleum Manager'}
}
'''

# Asynchronous activity execution
activity_async_response = fullcontact_client.verify.activity_async(email="[e-mail]")
activity_response = activity_async_response.result()
print(activity_response.json())
# Output: {'emails': 0.03}

FullContactClient.verify.match()

class: fullcontact.api.verify_api.VerifyClient

Parameters:

• **query: kwargs - (required)
• headers: dict - [optional]

query takes in MultiFieldReq.

Returns:

VerifyMatchResponse

class: fullcontact.response.verify_response.MatchResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_city(): bool - city flag from Verify Match Response
• get_region(): bool - region flag from Verify Match Response
• get_country(): bool - country flag from Verify Match Response
• get_continent(): bool - continent flag from Verify Match Response
• get_postalCode(): bool - postalCode flag from Verify Match Response
• get_familyName(): bool - familyName flag from Verify Match Response
• get_givenName(): bool - givenName flag from Verify Match Response
• get_phone(): bool - phone flag from Verify Match Response
• get_maid(): bool - maid flag from Verify Match Response
• get_email(): bool - email flag from Verify Match Response
• get_social(): bool - social flag from Verify Match Response
• get_nonId(): bool - nonId flag from Verify Match Response

FullContactClient.verify.match_async()

class: fullcontact.api.verify_api.VerifyClient

Parameters:

Same as that of FullContactClient.verify.match()

Returns:

Future[VerifyMatchResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): VerifyMatchResponse - VerifyMatchResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

FullContactClient.verify.signals()

class: fullcontact.api.verify_api.VerifyClient

Parameters:

• **query: kwargs - (required)
• headers: dict - [optional]

query takes in MultiFieldReq.

Returns:

VerifySignalsResponse

class: fullcontact.response.verify_response.VerifySignalResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_personIds(): List[str] - List of personIds from Signals response
• get_name(): dict - Name from Verify Signals response
• get_emails(): List[dict] - List of email objects from Verify Signals response
• get_phones(): List[dict] - List of phone objects from Verify Signals response
• get_maids(): List[dict] - List of maids objects from Verify Signals response
• get_nonIds(): List[dict] - List of nonIds objects from Verify Signals response
• get_panoIds(): List[dict] - List of panoIds objects from Verify Signals response
• get_ipAddresses(): List[dict] - List of ipAddress objects from Verify Signals response
• get_socialProfiles(): List[str] - List of Social Profiles from Verify Signals response
• get_demographics(): dict - Demographics from Verify Signals response
• get_employment(): dict - Employment from Verify Signals response
• get_locations(): List[dict] - List of location object from Verify Signals response

FullContactClient.verify.signals_async()

class: fullcontact.api.verify_api.VerifyClient

Parameters:

Same as that of FullContactClient.verify.signals()

Returns:

Future[VerifySignalsResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): VerifySignalsResponse - VerifySignalsResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.

FullContactClient.verify.activity()

class: fullcontact.api.verify_api.VerifyClient

Parameters:

• **query: kwargs - (required)
• headers: dict - [optional]

query takes in MultiFieldReq.

Returns:

VerifyActivityResponse

class: fullcontact.response.verify_response.VerifyActivityResponse

Instance variables

• is_successful: bool - Success flag
• response: requests.Response - Raw requests.Response object

Methods:

• json(): dict - Response JSON as dict
• get_message(): str - Response message or HTTP status message
• get_headers(): dict - Response headers
• get_emails(): float - email activity score from Verify Activity Response

FullContactClient.verify.activity_async()

class: fullcontact.api.verify_api.VerifyClient

Parameters:

Same as that of FullContactClient.verify.activity()

Returns:

Future[VerifyActivityResponse]

class: concurrent.Futures.Future

More on concurrent.Futures.Future: https://docs.python.org/3/library/concurrent.futures.html#future-objects

Useful Methods:

• result(): VerifyActivityResponse - VerifyActivityResponse object received once execution is completed
• add_done_callback(fn): None - Add a callback function to be executed on successful execution.