API Reference

Both components share the same base props. <aiprise-button> adds 3 additional props.

`<aiprise-frame>`

Embeds the verification flow directly in your page.

Prop	Type	Required	Applies To	Default	Description	Example
`mode`	`"SANDBOX" \| "PRODUCTION"`	✅	Both	—	Determines the API environment. Use `SANDBOX` for testing, `PRODUCTION` for live.	`"SANDBOX"`
`template-id`	`string`	✅	Both	—	Verification flow template from your AiPrise dashboard. Defines steps and checks required.	`"31c8cb17-c56c-..."`
`session-id`	`string`	—	Both	—	Resume a previously started session. Lets users continue where they left off.	`"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`
`callback-url`	`string`	—	Both	—	Webhook endpoint for final verification status changes (completed, failed). Receives POST requests.	`"http://yourcallbackurl.com"`
`events-callback-url`	`string`	—	Both	—	Webhook for real-time step events (document upload, step completion). Fires during the flow, unlike `callback-url`.	`"https://example.com/events"`
`client-reference-id`	`string`	—	Both	—	Your internal ID to link verification to a user/order in your system. Returned in webhooks.	`"SOME_ID_YOU_WANT_TO_ASSOCIATE"`
`client-reference-data`	`string` (JSON)	—	Both	—	Custom metadata attached to the session. Any JSON object — returned in webhooks.	`'{ "some_data": "some_value" }'`
`user-profile-id`	`string`	—	KYC	—	Link to a pre-created AiPrise user profile. Enables profile reuse across verifications.	`"f4c92a11-3b7e-4d8a-9e6f-1a2b3c4d5e6f"`
`business-profile-id`	`string`	—	KYB	—	Link to a pre-created AiPrise business profile for business verification flows.	`"f4c92a11-3b7e-4d8a-9e6f-1a2b3c4d5e6f"`
`user-data`	`string` (JSON)	—	KYC	—	Pre-fill user fields to reduce input and improve conversion. Editable by user. See `UserData`.	`'{ "first_name": "John", "last_name": "Doe", "email_address": "[email protected]" }'`
`business-data`	`string` (JSON)	—	KYB	—	Pre-fill business fields for business verification flows. See `BusinessData`.	`'{ "name": "Acme Corp", "country_code": "US", "website": "https://acme.com" }'`
`additional-info`	`string` (JSON)	—	Both	—	Pass custom metadata that doesn't fit standard fields. Returned in webhooks. See `AdditionalInfo`.	`'[{ "additional_info_type": "metadata", "additional_info_data": "value" }]'`
`ui-options`	`string` (JSON)	—	Both	—	Control localization and module behavior — set language, restrict allowed countries. See `UIOptions`.	`'{ "common": { "default_language": "en" }, "id_verification_module": { "allowed_country_code": "US" } }'`
`verification-options`	`string` (JSON)	—	Both	—	Configure AML thresholds, monitoring, and verification rules. See `VerificationOptions`.	`'{ "AML_CONFIG": { "fuzziness_score": 0.8, "exact_match": 0.9, "monitoring": true } }'`
`associated-email`	`string`	—	KYB	—	Email tied to the session. Used in business flows for saving progress.	`"[email protected]"`
`icon`	`string`	—	Both	AiPrise logo	Brand logo URL (40×40px recommended). Replaces the default AiPrise logo in the UI.	`"YOUR_40X40_LOGO_URL"`
`theme`	`string` (JSON)	—	Both	—	Brand the verification UI — colors, styling. For white-label integrations. See `ThemeOptions`.	`'{ "primary_color": "#0066cc", "background_color": "#f5f5f5" }'`

`<aiprise-button>` Only

Opens the verification flow in a modal. Inherits all <aiprise-frame> props plus:

Prop	Type	Required	Applies To	Default	Description	Example
`title`	`string`	—	Both	`"Verify with AiPrise"`	Button label text. Match your app's tone and language.	`"YOUR_BUTTON_TEXT"`
`color`	`string`	—	Both	AiPrise brand	Button background color (hex). Use your brand's primary color.	`"YOUR_BRAND_HEX_CODE"`
`text-color`	`string`	—	Both	`"#ffffff"`	Button text color (hex). Ensure contrast against `color` for accessibility.	`"BUTTON_TEXT_COLOR_HEX_CODE"`

JSON Structures

All JSON props accept stringified JSON strings.

`UserData`

Pre-fill user info in the verification form. Used with user-data prop. Applies to: KYC

Property	Type	Description	Example
`first_name`	`string`	First name. Pre-populates field, user can edit.	`"John"`
`middle_name`	`string`	Middle name. Helps with identity matching against official documents.	`"Michael"`
`last_name`	`string`	Last name / surname. Essential for ID document matching.	`"Doe"`
`date_of_birth`	`string`	Date of birth. Must be `YYYY-MM-DD`. Used for age/identity checks.	`"1990-01-15"`
`phone_number`	`string`	Phone in E.164 format. Used for SMS verification and contact.	`"+11234567890"`
`email_address`	`string`	Email. Used for notifications and account linking.	`"[email protected]"`
`ip_address`	`string`	User's IP. Enables fraud detection and geolocation checks.	`"192.168.1.1"`
`address`	`Address`	Full address object. Pre-fills address fields for proof-of-address checks.	See below

`Address`

Shared address structure used in UserData and BusinessData.

Property	Type	Description	Example
`address_street_1`	`string`	Primary street line (number + street name).	`"123 Main Street"`
`address_street_2`	`string`	Apt, suite, building — additional line.	`"Apt 4B"`
`address_city`	`string`	City / municipality.	`"New York"`
`address_state`	`string`	State / province code.	`"NY"`
`address_zip_code`	`string`	ZIP / postal code. Format varies by country.	`"10001"`
`address_country`	`string`	2-letter ISO country code.	`"US"`

`BusinessData`

Pre-fill business info for business verification flows. Used with business-data prop. Applies to: KYB

Property	Type	Description	Example
`name`	`string`	Legal / registered company name. Must match official documents.	`"Acme Corporation"`
`business_entity_id`	`string`	Your internal business entity ID or registry ID. Prevents duplicates.	`"ENT-123456"`
`tax_identification_number`	`string`	EIN, VAT, or local tax ID. Format varies by country.	`"12-3456789"`
`state_code`	`string`	State/province where business is registered.	`"NY"`
`country_code`	`string`	2-letter ISO country code of registration.	`"US"`
`website`	`string`	Business website URL. Used for legitimacy checks.	`"https://acme.com"`
`phone_numbers`	`string[]`	Business phone numbers in E.164 format.	`["+11234567890"]`
`addresses`	`Address[]`	Registered/mailing addresses. Multiple locations supported.	See above

`UIOptions`

Control localization and module-level behavior. Used with ui-options prop.

Top-level Modules

Property	Type	Applies To	Description
`common`	`object \| null`	Both	Shared settings across all modules.
`id_verification_module`	`object \| null`	Both	Controls the ID verification step.
`dynamic_user_question_group_module`	`object \| null`	KYC	Dynamic questions presented to the user.
`dynamic_business_question_group_module`	`object \| null`	KYB	Dynamic questions presented for business verification.
`dynamic_user_document_module`	`object \| null`	KYC	Dynamic document upload requirements for users.
`dynamic_business_document_module`	`object \| null`	KYB	Dynamic document upload requirements for businesses.

`common`

Property	Type	Description	Example
`default_language`	`string \| null`	ISO 639-1 language code. Sets verification UI language. Falls back to browser locale if unset. Supported: `en`, `fr`, `it`, `es`, `pt`, `de`, `pl`, `ja`, `ko`, `zh`, `ru`, `ar`.	`"en"`

`id_verification_module`

Property	Type	Description	Example
`allowed_country_code`	`string \| null`	2-letter ISO country code pre-selected in the onboarding UI.	`"US"`
`allowed_document_type`	`string \| string[] \| null`	Document type(s) pre-selected. Prefer array format — string is deprecated.	`["ID_CARD", "PASSPORT"]`

allowed_document_type is available in the verification URL flow but omitted from email-based and business officer endpoints.

`dynamic_user_question_group_module` / `dynamic_business_question_group_module`

Contains a questions object keyed by pattern Q01, Q02, etc.

Property	Type	Required	Description	Example
`type`	`QuestionType`	✅	One of: `SINGLE_CHOICE`, `MULTIPLE_CHOICE`, `BOOLEAN`, `TEXT`, `FILE`, `EMAIL`, `PHONE_NUMBER`, `SINGLE_SELECT`, `MULTIPLE_SELECT`, `DATE`, `PARAGRAPH`, `URL`	`"TEXT"`
`title`	`LanguageMap`	✅	Question text per locale.	`{ "en": "What is your name?" }`
`subtitle`	`LanguageMap`	—	Optional helper text below the question.	`{ "en": "As shown on ID" }`
`required`	`boolean`	✅	Whether the user must answer.	`true`
`order`	`integer`	✅	Display order (ascending).	`1`
`options`	`LanguageMap[]`	—	Choices for `SINGLE_CHOICE` / `MULTIPLE_CHOICE` / `*_SELECT` types.	`[{ "en": "Yes" }, { "en": "No" }]`

LanguageMap — object with optional keys: en, fr, it, es, pt, de, pl, ja, ko, zh, ru, ar.

`dynamic_user_document_module` / `dynamic_business_document_module`

Contains a documents array. Each entry:

Property	Type	Required	Description	Example
`file_type`	`string`	✅	Document type enum value.	`"BANK_STATEMENT"`
`required`	`boolean`	✅	Whether upload is mandatory.	`true`
`auto_run_check`	`boolean`	✅	Automatically run verification checks on upload.	`true`
`subtitle`	`string`	—	Optional description shown to the user.	`"Upload latest statement"`

`VerificationOptions`

Configure AML and verification rules. Used with verification-options prop.

Property	Type	Required	Description	Example
`AML_CONFIG`	`object`	—	Anti-Money Laundering settings. All sub-fields required if this object is provided.	—
`AML_CONFIG.fuzziness_score`	`number`	✅*	Fuzzy name matching threshold (0–1). Lower = stricter.	`0.8`
`AML_CONFIG.exact_match`	`number`	✅*	Exact name matching threshold (0–1). Typically higher than `fuzziness_score`.	`0.9`
`AML_CONFIG.monitoring`	`boolean`	✅*	Enable continuous AML monitoring and alerts.	`true`

Required when AML_CONFIG is provided.

`AdditionalInfo`

Pass custom metadata as an array of typed entries. Used with additional-info prop.

Property	Type	Description	Example
`additional_info_type`	`string`	Category identifier (e.g., `"custom_field"`, `"metadata"`). Helps organize data in webhooks.	`"metadata"`
`additional_info_data`	`any`	The data payload. Any JSON-serializable value — string, number, object, array.	`{"source":"web_app"}`

`ThemeOptions`

Brand the verification UI with custom colors. Used with theme prop.

Accepts a Record<string, string> — any key-value pairs with CSS color values.

Property	Type	Description	Example
`[key]`	`string`	Theme variable. Common keys: `primary_color`, `secondary_color`, `background_color`, `text_color`. Values should be valid CSS colors (hex, rgb).	`"#0066cc"`

<aiprise-frame>

<aiprise-button> Only

JSON Structures

UserData

Address

BusinessData

UIOptions

Top-level Modules

common

id_verification_module

dynamic_user_question_group_module / dynamic_business_question_group_module

dynamic_user_document_module / dynamic_business_document_module

VerificationOptions

AdditionalInfo

ThemeOptions