Skip to main content
POST
Creates a new onboarding widget. New widgets are created in draft status. The full config object is required and must contain every section. Live widgets require a verified business on the account. Sandbox widgets do not. Requires Authorization: Bearer $TOKEN.

Body

string
required
Human-readable name for this widget. 1 to 120 characters.
string
default:"blank"
Template identifier the widget was built from. 1 to 60 characters.
string
default:"sandbox"
One of sandbox or live. Creating a live widget returns 403 until the account has verified a business.
object
required
Full widget configuration. All six sections below are required.

config.branding

string
required
1 to 120 characters.
string
default:""
Logo URL, up to 2048 characters.
string
Storage public ID, up to 512 characters.
string
required
Hex colour, e.g. #6466AE.
string
required
One of sharp, soft, round.
string
required
1 to 200 characters.
string
required
1 to 600 characters.
string
required
1 to 200 characters.
string
required
1 to 600 characters.
string
default:""
Up to 200 characters.

config.modules

object
required
A map keyed by module ID (e.g. business_profile, cac_verification). Each value has enabled and required booleans, plus an optional placeholders map. See Module catalog for the 19 valid module IDs.
object
Optional input hints keyed by field name, up to 200 characters each and 50 entries per module. Field names must start with a letter, contain only letters and digits, and be at most 80 characters. For example: "business_profile": { "enabled": true, "required": true, "placeholders": { "legalName": "Your registered company name", "registeredAddress": "Your office address", "contactEmail": "Your work email" } }.These hints apply to text inputs, text areas and editable dropdowns in hosted and embedded widgets. Missing or blank hints use the default text. They do not change field labels, saved answers, validation or read-only fields. You can also edit them under Branding → Input placeholders in the widget editor. When updating a widget, send the complete configuration including any overrides you want to keep.

config.flow

string[]
required
Ordered array of module IDs.
boolean
required
boolean
required
integer
required
5 to 240.
string
default:""
Up to 2048 characters.
string
default:""
Up to 2048 characters.
string
default:""
Up to 2048 characters.

config.security

string[]
required
Up to 50 entries, each up to 255 characters.
string[]
required
Up to 250 two-letter country codes.
boolean
required
string[]
required
Up to 100 entries, each up to 64 characters.
boolean
required

config.risk

string
required
One of low, standard, enhanced.
integer
required
0 to 100.
integer
required
0 to 100.
boolean
required
boolean
required
boolean
required

config.notifications

boolean
required
boolean
required
string
default:""
Up to 200 characters.
string[]
required
Up to 20 entries, each up to 60 characters.
Returns 201 with the full widget object. Set the widget to live with Set widget status when ready.