Forms

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:

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

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:

1. Configure the form fields in your Wink Site.
2. After the user completes the Wink flow, call GET /alpha/forms filtered by userId to retrieve all form submissions for that user.
3. 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