Skip to content

Python SDK

You can integrate Alice Onboarding into your backend using directly our API (See our API Reference or using our open-source Python Client.

image

Tip

Check our GitHub repo to be aware of our latest releases and code examples.

1. Installation

pip install alice-onboarding

Warning

Required version of Python above 3.6

2. Getting Started

2.1. Config

Configure your credentials with Config class

from alice import Config

ALICE_ONBOARDING_API_KEY="<YOUR-API-KEY>"

config = Config(api_key=ALICE_ONBOARDING_API_KEY)

By default, this configure the production environment, if you want to use the sandbox environment, you have two options:

  • Add environment parameter on Config 

    from alice import Config, Environment

config = Config(api_key="<YOUR-API-KEY>", environment=Environment.SANDBOX)

  • Or, just export the ALICE_ENVIRONMENT environment variable 

    export ALICE_ENVIRONMENT=sandbox

2.2. Run an Onboarding flow

To manage the operations with Alice Onboarding API, use Onboarding class.

With the following code you can execute a complete Onboarding Flow:

  • Create a user
  • Add a selfie
  • Add both sides of a Document (Spanish idcard in this case)
  • Create a report
from alice import Config, Onboarding

ALICE_ONBOARDING_API_KEY="<YOUR-API-KEY>"

config = Config(api_key=ALICE_ONBOARDING_API_KEY)
onboarding = Onboarding.from_config(config)

user_id = onboarding.create_user(verbose=True).unwrap()

# Upload a selfie (Recommended 1-second video)
SELFIE_MEDIA_DATA=open(f"{RESOURCES_PATH}/selfie.png", "rb").read()
onboarding.add_selfie(
    user_id=user_id, media_data=SELFIE_MEDIA_DATA
)

# Create and upload front and back side from a document
document_id = onboarding.create_document(
    user_id=user_id, type="idcard", issuing_country="ESP"
).unwrap()

DOCUMENT_FRONT_MEDIA_DATA=open(f"{RESOURCES_PATH}/idcard_esp_front_example.png", "rb").read()
onboarding.add_document(
    user_id=user_id,
    document_id=document_id,
    media_data=DOCUMENT_FRONT_MEDIA_DATA,
    side="front",
    manual=True,

)

DOCUMENT_BACK_MEDIA_DATA=open(f"{RESOURCES_PATH}/idcard_esp_back_example.png", "rb").read()
onboarding.add_document(
    user_id=user_id,
    document_id=document_id,
    media_data=DOCUMENT_BACK_MEDIA_DATA,
    side="back",
    manual=True,

)

# Generate the report
report = onboarding.create_report(
    user_id=user_id
).unwrap()

Warning

The Python Client uses the meiga package to return Result objects. It returns a monad (Success or Failure). To unwrap the result, just use unwrap() function.

Tip

You can check a reproducible script example on Github

Execute the following commands on your terminal to execute the example:

$ git clone https://github.com/alice-biometrics/onboarding-python
$ cd onboarding-python
$ export ONBOARDING_API_KEY="<YOUR-API-KEY>"
$ python examples/onboarding.py

Info

This class deals with authentication automatically. To know more about authentication, please check Advanced Authentication.

3. Additional features

Warning

These features could not be available by default. If you obtain a HTTP Error (405 method not allowed). Please, contact us to make them available for your credentials.

3.1. Certified Onboarding

If you need certify your user data, you can create and retrieve a certified PDF Report with the following code:

from alice import Config, Onboarding

ALICE_ONBOARDING_API_KEY="<YOUR-API-KEY>"

config = Config(api_key=ALICE_ONBOARDING_API_KEY)
onboarding = Onboarding.from_config(config)

user_id = onboarding.create_user(verbose=True).unwrap()

# Create Certificate
certificate_id = onboarding.create_certificate(
    user_id=user_id
).unwrap_or_throw()

# Retrieved Certificate from certificate_id
certificate = onboarding.retrieve_certificate(
    user_id=user_id, certificate_id=certificate_id
).unwrap_or_throw()

Tip

You can check a reproducible script example on Github

Execute the following commands on your terminal to execute the example:

$ git clone https://github.com/alice-biometrics/onboarding-python
$ cd onboarding-python
$ export ONBOARDING_API_KEY="<YOUR-API-KEY>"
$ python examples/onboarding_with_certificate.py

3.2. User Screening

Alice Onboarding API bring us the opportunity of screening a user over different databases & lists (sanctions, PEP, etc)..

from alice import Config, Onboarding

ALICE_ONBOARDING_API_KEY="<YOUR-API-KEY>"

config = Config(api_key=ALICE_ONBOARDING_API_KEY)
onboarding = Onboarding.from_config(config)

user_id = onboarding.create_user(verbose=True).unwrap()

# Screening
screening = onboarding.screening(
    user_id=user_id
).unwrap_or_throw()
assert isinstance(screening, dict)

# Add user to monitoring list
onboarding.screening_monitor_add(
    user_id=user_id
).unwrap_or_throw()

open_alerts = onboarding.screening_monitor_open_alerts(
).unwrap_or_throw()
assert isinstance(open_alerts, dict)

Tip

You can check a reproducible script example on Github

Execute the following commands on your terminal to execute the example:

$ git clone https://github.com/alice-biometrics/onboarding-python
$ cd onboarding-python
$ export ONBOARDING_API_KEY="<YOUR-API-KEY>"
$ python examples/onboarding_with_screening.py

3.3. Webhooks

Configure your webhooks through the API with the Webhooks object.

from alice import Config, Webhooks

ALICE_ONBOARDING_API_KEY="<YOUR-API-KEY>"

config = Config(api_key=ALICE_ONBOARDING_API_KEY)
webhooks_client = Webhooks.from_config(config)

# Check Available events
available_events = webhooks_client.get_available_events(verbose).unwrap()
selected_event = available_events[0]

# Create a new Webhook
webhook = Webhook(
    active=True,
    post_url="http://google.com",
    api_key="b0b905d6-228f-44bf-a130-c85d7aecd765",
    event_name=selected_event.get("name"),
    event_version=selected_event.get("version"),
    secret=str(secrets.token_hex(20)),
)
webhook_id = webhooks_client.create_webhook(webhook, verbose).unwrap()

# Send a ping using configured webhook
result = webhooks_client.ping_webhook(webhook_id, verbose)

Tip

You can check a reproducible script example on Github

Execute the following commands on your terminal to execute the example:

$ git clone https://github.com/alice-biometrics/onboarding-python
$ cd onboarding-python
$ export ONBOARDING_API_KEY="<YOUR-API-KEY>"
$ python examples/onboarding_with_webhooks.py

Info

You can configure your webhooks using the Onboarding Dashboard. Please check the documentation on Webhooks.

4. Advanced Authentication

4.1. Tokens Management

To manage authorization and token creations, use Auth class.

Available tokens:

Type Token Info
BACKEND_TOKEN Used to secure global requests.
BACKEND_TOKEN_WITH_USER Used to secure global requests include user_id information embedded
USER_TOKEN Used to secure requests made by the users on their mobile devices or web clients

To create a BACKEND_TOKEN_WITH_USER and a USER_TOKEN you will need a valid user_id obtained from Alice Onboarding API. Use Auth class to manage Alice Onboarding tokens.

from alice import Config, Auth

ALICE_ONBOARDING_API_KEY="<YOUR-API-KEY>"

config = Config(api_key=ALICE_ONBOARDING_API_KEY)

auth = Auth.from_config(config)

backend_token = auth.create_backend_token().unwrap)
backend_token_with_user = auth.create_backend_token(
    user_id=user_id
).unwrap()
user_token = auth.create_user_token(user_id=user_id).unwrap()

Tip

You can check a reproducible script example on Github

Execute the following commands on your terminal to execute the example:

$ git clone https://github.com/alice-biometrics/onboarding-python
$ cd onboarding-python
$ export ONBOARDING_API_KEY="<YOUR-API-KEY>"
$ python examples/auth.py