Web SDK | Developers Amani Ai

Overview

The Amani Web SDK lets you embed a full KYC verification flow, live video verification, and biometric payment (Bio Pay) directly in any web application — without shipping a native mobile app. The SDK runs in the user's browser and handles all capture, submission, and result routing automatically.

🪪

KYC Verification

Document capture, selfie matching, and background checks — all in the browser.

📹

Videocall (Video KYC)

Live agent-assisted verification over a WebRTC video connection. Enabled with a single URL parameter.

💳

Bio Pay

Biometric payment authentication using facial recognition and PIN verification.

Integration Workflow

1️⃣

Authenticate

Obtain a server-side access token using your API credentials.

2️⃣

Create Profile

3️⃣

Generate SDK URL

Create a secure, short-lived verification URL for the session.

4️⃣

Redirect User

Send the user to the SDK URL via direct redirect or iframe.

5️⃣

Handle Callback

Receive the verification result on your return_url.

Step 1 — Authenticate

Obtain an access token by logging in with your API credentials. This request must be performed server-side — never expose your credentials in client-side code.

Region	Base URL
Europe	`https://eu.amani.ai`
Turkey	`https://tr.amani.ai`
UAE	`https://ae.amani.ai`

POST https://{region}.amani.ai/api/v2/user/login/

curl --location --request POST 'https://{region}.amani.ai/api/v2/user/login/' \
  --form 'username="your_email@account.com"' \
  --form 'password="your_password"'

Use the access token from the response for all subsequent API calls with the Authorization: Bearer {token} header.

Step 2 — Create or Get Profile

Create a customer profile. If a customer already exists with the provided id_card_number, the existing profile is returned — no duplicate profiles are created.

POST https://{region}.amani.ai/api/v2/profile

curl --location --request POST 'https://{region}.amani.ai/api/v2/profile' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'id_card_number="CUSTOMER_ID_NUMBER"' \
  --form 'name="Customer Name"' \
  --form 'email="customer@email.com"' \
  --form 'phone="+905..."'

Save the id (Profile ID) from the response — you will need it in the next step.

Step 3 — Generate Verification URL

Generate a secure, short-lived URL for your customer to complete the verification process.

POST https://{region}.amani.ai/api/v2/profile/url

curl --location --request POST 'https://{region}.amani.ai/api/v2/profile/url' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "profile": PROFILE_ID,
    "web_sdk_url": "https://verify.amani.ai",
    "geo_location": false,
    "language": "en",
    "return_url": "https://yourdomain.com/verification-complete",
    "deep_link": ""
  }'

Parameter	Type	Required	Description
`profile`	string	✅ Yes	Profile ID from Step 2
`web_sdk_url`	string	✅ Yes	Base URL for Amani's Web SDK (typically https://verify.amani.ai)
`return_url`	string	✅ Yes	URL to redirect user after verification completes
`geo_location`	boolean	⚪ Optional	Enable geolocation tracking (default: false)
`language`	string	⚪ Optional	Language code (default: en) — see Supported Languages
`deep_link`	string	⚪ Optional	Custom deep link for mobile integration

The response contains a short_url — save this for the next step:

{
  "short_url": "https://verify.amani.ai?pid=be1a2e01HX79R...A757XPS&server_url=https://{region}.amani.ai"
}

📹 Videocall Integration

To enable Videocall (live agent-assisted KYC), append /call to your web_sdk_url:

Mode	web_sdk_url value
Standard KYC	`https://verify.amani.ai`
Videocall KYC	`https://verify.amani.ai/call`

Step 4 — Redirect the User

Direct your users to the short_url from Step 3. Choose between a direct redirect or embedding via iframe.

🔀

Option 1 — Direct Redirect

Redirect the user's browser directly to the Amani Web SDK interface. Best for full-page verification flows where the user leaves your app temporarily and returns after completing verification.

window.location.href = short_url;

🖼️

Option 2 — iFrame Embed

Embed the verification flow inside your application without navigating away. Ideal for single-page apps where you want to keep the user on-site throughout the entire process.

<iframe
  src="{short_url}"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Step 5 — Handle the Callback

After the user completes verification (or encounters an error), they are automatically redirected to your return_url with the following query parameters appended:

✅

status

The customer's verification status — e.g. complete or incomplete.

🪪

customer_id

The Amani Profile ID for this customer.

⚠️

errors

A comma-separated list of error codes if the process failed. Empty on success.

Example callback URL your server will receive:

https://yourdomain.com/verification-complete?status=complete&customer_id=abc123&errors=

Error Code Reference

Code	Meaning
`401`	Unauthorized — token is invalid or expired
`404`	Not Found — user profile could not be located
`500`	Internal Server Error

Bio Pay Integration

Bio Pay is a specialized module for biometric payment authentication using facial recognition and PIN verification. It uses a pre-generated bio_token instead of the standard KYC flow.

Prerequisites: A valid user with the necessary permissions, and the Biopay feature enabled on your account.

Direct users to the Bio Pay interface using a pre-generated bio_token:

https://verify.amani.ai?bio_token={YOUR_BIO_TOKEN}&server_url={YOUR_SERVER_URL}

Parameter	Description
`bio_token`	Pre-generated authentication token for the user
`server_url`	Your regional API server URL (e.g. `https://eu.amani.ai`)

Need more details?

Getting Started →API Reference →Supported Languages →