Getting Started

This guide explains how to generate a valid verification link and what link settings control the user experience.

Prerequisites

• API credentials for your Amani environment
• A backend service that can call our servers securely
• A customer profile or session token (pid) generated from our servers
• A return link in your application for the user to land on after verification

Step 1 - Authenticate Server Side

Use your backend to call the login endpoint and store the access token (JWT).

curl --location --request POST 'https://{region}.amani.ai/api/v2/user/login/' \
--form 'username="[email protected]"' \
--form 'password="your_password"'

Step 2 - Create or Retrieve Profile

Create a profile or retrieve an existing one using the customer's ID number.

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="[email protected]"' \
--form 'phone="+905..."'

Step 3 - Generate a Verification Link

Create a short link for the customer session.

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": ""
  }'

Expected response:

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

Required Link Settings

Setting	Required	Description
pid	Yes	Session token used to start the verification tool (SDK)
server_url	Yes	Server address that the verification tool (SDK) connects to

Optional Link Settings

Setting	Required	Description
rl	No	Return link override for the final redirect
ln	No	Language override (for example en, tr, ar)
gl	No	Location sharing toggle (false disables location collection)
tk	No	Access token override for legacy integrations
bu	No	Base server address override
bio_token	No	Payment access token — enables BioPay when provided with server_url

Launch Modes

Standard Identity Verification (KYC)

The user opens the verification link and follows the document and selfie steps.

• Entry: main screen
• Typical next screen: Terms and Conditions (if enabled) or the first required step

Video Call

The link points to the call screen. The verification tool (SDK) routes the user directly into the call flow.

• Entry: call screen
• Final screen: Call Completion screen

BioPay

Launched with a payment access token (user_token) and server address (server_url).

• Entry: BioPay screen

BioLogin

Launched with BioLogin-specific link settings (session token and server address) for selfie login.

• Entry: main BioLogin screen
• Legacy alternate entry screen also available

Entity Verification

Launched with entity links that route to the company verification flow.

• Entry: entity start screen
• Next screen chosen by our servers: entity document upload or entity information form

warning

Never expose your account login credentials in client-side code. Always generate verification links on your backend server.