incognia-python 3.7.1

Python lightweight client library for Incognia APIs

Incognia API Python Client 🐍

Installation

You can install the IncogniaAPI using the following command:

pip install incognia-python

Usage

Configuration

Before calling the API methods, you need to create an instance of the IncogniaAPI class.

from incognia.api import IncogniaAPI

api = IncogniaAPI('client-id', 'client-secret')

HTTP keep-alive is enabled by default to reuse connections across requests, reducing latency and overhead for high-throughput usage. The max_connections parameter controls the connection pool size (defaults to 10). You can still disable keep-alive explicitly if needed. IncogniaAPI is a singleton, so these options must be configured on the first IncogniaAPI(...) call in a process. If an instance was already created, calling IncogniaAPI(...) again with different keep_alive or max_connections values will reuse the existing instance rather than reconfiguring it:

api = IncogniaAPI('client-id', 'client-secret', keep_alive=True, max_connections=20)

Incognia API

The implementation is based on the Incognia API Reference.

Authentication

Authentication is done transparently, so you don't need to worry about it.

Registering New Signup

This method registers a new signup for the given request token and a structured address, an address line or coordinates, returning a dict, containing the risk assessment and supporting evidence:

from incognia.api import IncogniaAPI
from incognia.models import StructuredAddress, Coordinates

api = IncogniaAPI('client-id', 'client-secret')

# with structured address, a dict:
structured_address: StructuredAddress = {
    'locale': 'en-US',
    'country_name': 'United States of America',
    'country_code': 'US',
    'state': 'NY',
    'city': 'New York City',
    'borough': 'Manhattan',
    'neighborhood': 'Midtown',
    'street': 'W 34th St.',
    'number': '20',
    'complements': 'Floor 2',
    'postal_code': '10001',
    'county': 'New York County'
}
assessment: dict = api.register_new_signup('request-token', structured_address=structured_address)

# with address line:
address_line: str = '350 Fifth Avenue, Manhattan, New York 10118'
assessment: dict = api.register_new_signup('request-token', address_line=address_line)

# with coordinates, a dict:
coordinates: Coordinates = {
    'lat': 40.74836007062138,
    'lng': -73.98509720487937
}
assessment: dict = api.register_new_signup('request-token', address_coordinates=coordinates)

# with external_id:
external_id: str = 'external-id'
assessment: dict = api.register_new_signup('request-token', external_id=external_id)

# with policy_id:
policy_id: str = 'policy-id'
assessment: dict = api.register_new_signup('request-token', policy_id=policy_id)

# with account_id:
account_id: str = 'account-id'
assessment: dict = api.register_new_signup('request-token', account_id=account_id)

Registering Feedback

This method registers a feedback event for the given identifiers (optional arguments) related to a signup, login or payment.

import datetime as dt
from incognia.api import IncogniaAPI
from incognia.feedback_events import FeedbackEvents  # feedbacks are strings.

api = IncogniaAPI('client-id', 'client-secret')

api.register_feedback(FeedbackEvents.ACCOUNT_TAKEOVER,
                      occurred_at=dt.datetime(2024, 7, 22, 15, 20, 0, tzinfo=dt.timezone.utc),
                      request_token='request-token',
                      account_id='account-id')

Registering Payment

This method registers a new payment for the given request token and account, returning a dict, containing the risk assessment and supporting evidence.

from typing import List
from incognia.api import IncogniaAPI
from incognia.models import TransactionAddress, PaymentValue, PaymentMethod

api = IncogniaAPI('client-id', 'client-secret')

addresses: List[TransactionAddress] = [
    {
        'type': 'shipping',
        'structured_address': {
            'locale': 'pt-BR',
            'country_name': 'Brasil',
            'country_code': 'BR',
            'state': 'SP',
            'city': 'São Paulo',
            'borough': '',
            'neighborhood': 'Bela Vista',
            'street': 'Av. Paulista',
            'number': '1578',
            'complements': 'Andar 2',
            'postal_code': '01310-200'
        },
        'address_coordinates': {
            'lat': -23.561414,
            'lng': -46.6558819
        }
    }
]

payment_value: PaymentValue = {
    'amount': 5.0,
    'currency': 'BRL'
}

payment_methods: List[PaymentMethod] = [
    {
        'type': 'credit_card',
        'credit_card_info': {
            'bin': '123456',
            'last_four_digits': '1234',
            'expiry_year': '2027',
            'expiry_month': '10'
        }
    },
    {
        'type': 'debit_card',
        'debit_card_info': {
            'bin': '123456',
            'last_four_digits': '1234',
            'expiry_year': '2027',
            'expiry_month': '10'
        }
    }
]

policy_id: str = 'policy-id'

assessment: dict = api.register_payment('request-token',
                                        'account-id',
                                        'external-id',
                                        addresses=addresses,
                                        payment_value=payment_value,
                                        payment_methods=payment_methods,
                                        policy_id=policy_id)

Registering Login

This method registers a new login for the given request token and account, returning a dict, containing the risk assessment and supporting evidence.

from incognia.api import IncogniaAPI

api = IncogniaAPI('client-id', 'client-secret')

policy_id: str = 'policy-id'

assessment: dict = api.register_login('request-token', 
                                      'account-id', 
                                      'external-id', 
                                      policy_id='policy_id')

Error Handling

Every method call can throw IncogniaHTTPError and IncogniaError.

IncogniaHTTPError is thrown when the API returned an unexpected http status code.

IncogniaError represents unknown errors, like required parameters none or empty.

How to Contribute

Your contributions are highly appreciated. If you have found a bug or if you have a feature request, please report them at this repository issues section.

Development

Versioning

This project uses Semantic Versioning, where version follows v{MAJOR}.{MINOR}.{PATCH} format. In summary:

• Major version update - Major functionality changes. Might not have direct backward compatibility. For example, multiple public API parameter changes.
• Minor version update - Additional features. Major bug fixes. Might have some minor backward compatibility issues. For example, an extra parameter on a callback function.
• Patch version update - Minor features. Bug fixes. Full backward compatibility. For example, extra fields added to the public structures with version bump.

Release

On GitHub, you should merge your changes to the main branch, create the git versioning tag and finally push those changes:

$ git checkout main
$ git pull
$ git merge <your_branch>
$ git tag -a v<version> -m "<description>"
$ git push origin HEAD --tags

• example:

$ git checkout main
$ git pull
$ git merge feat/some-feature
$ git tag -a v2.1.0 -m "This release adds some feature..."
$ git push origin HEAD --tags

Our CI will build images with the tagged version and publish them to our PyPI repository.

What is Incognia?

Incognia is a location identity platform for mobile apps that enables:

• Real-time address verification for onboarding
• Frictionless authentication
• Real-time transaction verification

License