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.

https://img.shields.io/github/release/alice-biometrics/onboarding-python/all.svg

See also

Check the 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)

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 an 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>"
verbose=True

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 use the meiga package to return Result objects. It returns a monad (Success or Failure). To unwrap the result, just use unwrap() function.

See also

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

Note

This class deals with authentication automatically. To know more about authentication, please check (see).

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:

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

# Save PdfReport data to a file
with open(f"certificate_{certificate_id}.pdf", "wb") as outfile:
    outfile.write(certificate)

certificates = onboarding.retrieve_certificates(
    user_id=user_id
).unwrap_or_throw()

See also

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

# Screening
screening = onboarding.screening(
    user_id=user_id
).unwrap_or_throw()

assert isinstance(screening, dict)

# Screening (with detail)
detailed_screening = onboarding.screening(
    user_id=user_id, detail=True
).unwrap_or_throw()
assert isinstance(detailed_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)

See also

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>"
verbose=True

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)

See also

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

Note

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>"
verbose=True
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()

See also

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

4.2. Sandbox

Caution

Only for early stages of integration

To manage the operations with the Sandbox API, use the Sandbox class.

from alice import Config, Sandbox

ONBOARDING_TRIAL_TOKEN="<YOUR-TRIAL-TOKEN>"
verbose=True
email="example@alicebiometrics.com"

config = Config(trial_token=trial_token)

sandbox = Sandbox.from_config(config)

user_id = sandbox.create_user(
    user_info=UserInfo(email=email)
).unwrap()
user_token = sandbox.get_user_token(email=email).unwrap()
user = sandbox.get_user(email=email).unwrap()
sandbox.delete_user(email=email).unwrap()

See also

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_TRIAL_TOKEN="<YOUR-TRIAL-TOKEN>"
$ python examples/sandbox.py