Link events are sent to your client (via the initializing callbacks) and will give you visibility into what is happening in the modal as the user moves through Pinwheel Link. It is up to you to determine how to use these events.

The onEvent callback is called with parameters (eventName: string, eventPayload: T) where T is the payload format corresponding to the event name found in this document below.

📘
Alternatively, you may use one of the specialized initialization callback parameters. These are convenient methods offering the same payloads as onEvent, but tailored for specific events.

Core Events

Link events inform you about user actions within the Pinwheel Link modal. It is up to you to determine how to use these events for tracking.

open

Modal was opened.

Payload

Empty object, {}.

exit

Modal was exited.

Payload (with error)

Key	Type	Description
`type`	string	Error type is the broad category of error. Read more here.
`code`	string	Error code is the specific error code. Read more here.
`message`	string	The error message shown to the end user.
`pendingRetry`	boolean	Sometimes jobs fail on the initial attempt. This field indicates if the job that has errored will be retried or not. Retries occur asynchronously and within 24 hours. The result of this retried job will be sent via a webhook.

Payload (without error)

Empty object, {}.

success

User reached the success screen. For direct deposit and card switch jobs, this will occur once for each job that completes successfully. For all other jobs this event will fire when the user logs in successfully, as these jobs are completed in the background.

Payload (SDK v3)

Key	Type	Description
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.
`platformId`	string	The uuid of the platform that the user uses.
`job`	string	Can be `'login'` or `direct_deposit_switch`. If you created a link token with only read jobs you will receive `'login'` here. This event means that the user has successfully logged in to their system and thus all read jobs will run subsequently asynchronously.* If your link token contains the job `direct_deposit_switch`, you will receive `'direct_deposit_switch'` here. This event means that the user has successfully switched their direct deposit to the specified account. Any read jobs contained in your link token will run subsequently asynchronously.* * Read job results may be retrieved via webhooks.
`params.action`	number	Optional. Only present if the link token has `direct_deposit_switch` and the user succeeds. Can be `full_switch` or `partial_switch`.
`params.allocation.type`	string	Optional. This key is only present when the `params.action` is `partial_switch`. Can be `remainder`, `amount`, or `percentage`.
`params.allocation.value`	number	Optional. This key is only present when the `params.allocation.type` is `amount` or `percentage`.

Payload (SDK v2)

Key	Type	Description
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.
`platformId`	string	The uuid of the platform that the user uses.
`job`	string	Can be `'login'` or `direct_deposit_switch`. If the job is `login`, the user has successfully logged in to their system and thus all read jobs will run subsequently asynchronously. If the job is `direct_deposit_switch`, the user has successfully switched their direct deposit to the specified account.
`params.amount.value`	number	Optional. Only present if the link token has `direct_deposit_switch` and the user succeeds. This is the value of the switch.
`params.amount.unit`	string	Optional. Only present if the link token has `direct_deposit_switch` and the user succeeds. The unit may be `"%"` or `"$"`.

error

User was shown an error. You can find more detail on Link errors and error handling here.

NOTE: Not all errors are terminal errors; e.g. a user may input incorrect credentials and still proceed.

Payload

Key	Type	Description
`type`	string	Error type is the broad category of error. Read more here.
`code`	string	Error code is the specific error code. Read more here.
`message`	string	The error message shown to the end user.
`pendingRetry`	boolean	Sometimes jobs fail on the initial attempt. This field indicates if the job that has errored will be retried or not. Retries occur asynchronously and within 24 hours. The result of this retried job will be sent via a webhook.

Employer/Platform Events

These events give insight into the employer or platform selected by the user or customer.

For On Demand Updates these events are not sent since the account_id is already associated with a platform.

select_employer

User selected an employer.

For On Demand Updates this event is not sent since the account_id is already associated with a platform.

Payload

Key	Type	Description
`selectedEmployerId`	string	The uuid of the employer selected by the user in the search page.
`selectedEmployerName`	string	The name of the employer selected by the user in the search page.

select_platform

User selected a platform

Payload

Key	Type	Description
`selectedPlatformId`	string	The uuid of the platform selected by the user in the search page.
`selectedPlatformName`	string	The name of the platform selected by the user in the search page.

incorrect_platform_given

The platform that was used to create the token was flagged as incorrect by the end user.

Payload

Empty object, {}.

Login Events

These events give insight into user login actions.

login_attempt

User has submitted login attempt for the first time.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has attempted to log in to.

login

User logged in successfully.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has logged in to.
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.

Direct Deposit Switch Events

These events give insight into the employer or platform selected by the user or customer.

input_allocation

User has submitted an allocation. Depending on the user's actions or your token creation parameters, you may receive a form of the payload described below.

Payload (SDK v3)

Key	Type	Description
`action`	string	Optional. Can be `full_switch` or `partial_switch`. May not be present for all platforms.
`allocation.type`	string	Optional. This key is only present when the `action` is `partial_switch`. Can be `remainder`, `amount`, or `percentage`.
`allocation.value`	number	Optional. This key is only present when the `allocation.type` is `amount` or `percentage`.

Payload (SDK v2)

Key	Type	Description
`action`	string	Can be `full_switch` or `partial_switch`.
`allocation.type`	string	Optional. This key is only present when the `action` is `partial_switch`. Can be `remainder`, `amount`, or `percentage`.
`allocation.value`	number	Optional. This key is only present when the `allocation.type` is `amount` or `percentage`.

input_amount (deprecated)

Not available in SDK version 3.

User inputted an amount. Note that this event is deprecated in favor of input_allocation, which provides more detail on what was input by the user.

Payload

Key	Type	Description
`value`	number	The value of the switch.
`unit`	string	Either `'$'` or `'%'` if the switch was an amount switch or a percentage switch, respectively.

Document Uploads Events

These events give insight into manual document uploads.

doc_uploads_begin

User has started the doc uploads flow.

Payload

Empty object, {}.

doc_uploads_submitted

User has submitted documents for upload.

Payload

Key	Type	Description
`uploadedDocumentSubmittedCount`	number	The number of documents submitted by the user.

Direct Deposit Form Events

dd_form_begin

User has begun the process to create a direct deposit form.

Payload

Empty object, {}.

dd_form_create

User has successfully created a direct deposit form, which is available at the returned URL.

Payload

Key	Type	Description
`url`	string	The URL of the generated direct deposit form.

dd_form_download

User has downloaded or shared the direct deposit form PDF.

Payload

Empty object, {}.

Navigation Events

screen_transition

User has transitioned to a new screen within the modal.

Payload

Key	Type	Description
`screen_name`	string	The name of the screen that was encountered. See options for this key below.
`selectedEmployerId`	string	Optional. Only available if the `screen_name` is `"LOGIN"`. The uuid of the selected employer.
`selectedEmployerName`	string	Optional. Only available if the `screen_name` is `"LOGIN"`. The name of the selected employer.
`selectedPlatformId`	string	Optional. Only available if the `screen_name` is `"LOGIN"`. The uuid of the selected platform.
`selectedPlatformName`	string	Optional. Only available if the `screen_name` is `"LOGIN"`. The name of the selected platform.

See options for screen_name below.

Screen Names

Note that all possible screens are not captured below. New screens may be added and your code should handle it.

`screen_name`	Description
`SEARCH_DEFAULT`	Default search screen after the initial intro page.
`SEARCH_RESULTS`	Results screen when the user starts a search from the `SEARCH_DEFAULT` screen.
`SEARCH_PLATFORM_ONLY`	From the `SEARCH_RESULTS` screen, the user is able to search through a list filtered for platforms only.
`PROVIDER_CONFIRMATION`	Provider confirmation screen. When some employers or platforms (e.g. Workday) are initially selected, the user is prompted to then confirm their specific employer/platform before logging in.
`LOGIN`	Login screen once the user has selected a platform or employer from search.
`DD_AMOUNT_SELECTION`	Direct deposit amount selection screen after the user has successfully logged in.
`DD_CONFIRMATION`	Confirmation screen before a direct deposit switch is performed.
`JOB_SUCCESS`	Job success screen (e.g. direct deposit switch succeeded).
`JOB_ERROR`	Job error screen (e.g. direct deposit switch failed).
`EXIT_CONFIRMATION`	Exit confirmation screen when the user presses the modal close button.

Other Events

other_event

We periodically test new events that will appear as other_event. These are typically experimental in nature and may change in the future, so they're safe to ignore. If you have any feedback or requests for new Link events, please let us know!