The Forms API provides access to data submitted by users through Wink Site forms. When users accomplish each step of the Wink Site flow, Smile API captures and stores those responses, making them retrievable via this API.

Forms are a flexible mechanism for collecting user-declared information alongside the verified data that Smile retrieves from connected accounts. Common use cases include collecting user consent, personal details, income declarations, or any other structured information your workflow requires before or after account connection.

📘
Alpha Notice
The Forms API is currently in Alpha. The API endpoints are prefixed with /alpha/forms. Features, schemas, and behaviors may change as the API is stabilized.

How Forms Work

Forms are created and configured through the Wink Site setup in the Developer Portal. Each Wink Site can include one or more screens that are presented to the user and may be programmed to follow a certain set of visibility and branching rules. When a user submits a form, Smile stores the response and associates it with that user's session.

Each form submission creates a Form object containing:

The form name and its reference identifier (as configured in your Wink Site)
The IDs of the Wink Site and Wink Site session under which the form was submitted
The user's submitted field values in a flexible key-value data object

Because the data payload is schema-free, its structure varies based on how each form is configured in your Wink Site. You should treat the field names and types as defined by your own form configuration.

Retrieving Form Submissions

Filtering Results

The List Forms endpoint returns all form submissions under your tenantId by default. To avoid large, unscoped result sets, always filter your queries using one or more of the following parameters:

Parameter	Description
`userId`	Filter submissions by a specific user ID
`winkSiteId`	Filter submissions by a specific Wink Site
`startDate`	Start of the date range for form submission date (YYYY-MM-DD)
`endDate`	End of the date range for form submission date (YYYY-MM-DD)

Pagination

The List Forms endpoint uses cursor-based pagination. The response includes a nextCursor value that you pass as the cursor parameter in your next request to retrieve the following page of results. If nextCursor is null, there are no further results.

The default page size is 10 items, with a maximum of 150 items per request.

The Form Object

Attribute	Type	Description
id	string	Unique ID of the form submission
createdAt	date-time	Date and time the form was submitted, in ISO 8601 format
name	string	Name of the form as configured in the Wink Site. Nullable
userId	string	ID of the user who submitted the form
winkSiteId	string	ID of the Wink Site where the form was submitted
winkSiteSessionId	string	ID of the Wink Site session under which the form was submitted
reference	string	Reference identifier for the form, as defined in the Wink Site configuration
data	object	Key-value object containing the fields submitted by the user. Structure varies based on form configuration

Notes on the `data` field

The data object is schema-free. Field names and value types are determined by your Wink Site form configuration.
Fields not filled in by the user may be absent from the data object or present with a null value, depending on the form configuration.
Do not rely on the presence of any particular field unless it is configured as required in your Wink Site.

Common Use Cases

Collecting User-Declared Information

Forms allow you to capture user-declared details — such as self-reported income, employment status, or contact information — alongside verified data from connected accounts. This gives you a complete picture of the user's submitted profile within a single session.

Suggested approach:

Configure the form fields in your Wink Site.
After the user completes the Wink flow, call GET /alpha/forms filtered by userId to retrieve all form submissions for that user.
Match forms to specific sessions using winkSiteSessionId.

Retrieving a Specific Submission

If you have stored the form_id from a previous list call or from your own records, use GET /alpha/forms/{id} to retrieve that specific submission directly.

Reconciling Forms with Other Data

The winkSiteSessionId is the key field for reconciling form submissions with other data collected in the same session. Use it to join form data with account connection events, archived documents, or other data points retrieved during the same Wink flow.

Endpoints

Endpoint
List Forms	`GET /alpha/forms`
Get Form	`GET /alpha/forms/{id}`