GuidesAPI ReferenceChangelog
Log In
Guides

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)

KeyTypeDescription
typestringError type is the broad category of error. Read more here.
codestringError code is the specific error code. Read more here.
messagestringThe error message shown to the end user.
pendingRetrybooleanSometimes 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)

KeyTypeDescription
accountIdstringThe newly created uuid that signifies the relation between the user and the platform.
platformIdstringThe uuid of the platform that the user uses.
job stringCan 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.actionnumberOptional. Only present if the link token has direct_deposit_switch and the user succeeds. Can be full_switch or partial_switch.
params.allocation.typestringOptional. This key is only present when the params.action is partial_switch. Can be remainder, amount, or percentage.
params.allocation.valuenumberOptional. This key is only present when the params.allocation.type is amount or percentage.

Payload (SDK v2)

KeyTypeDescription
accountIdstringThe newly created uuid that signifies the relation between the user and the platform.
platformIdstringThe uuid of the platform that the user uses.
job stringCan 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.valuenumberOptional. Only present if the link token has direct_deposit_switch and the user succeeds. This is the value of the switch.
params.amount.unitstringOptional. 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

KeyTypeDescription
typestringError type is the broad category of error. Read more here.
codestringError code is the specific error code. Read more here.
messagestringThe error message shown to the end user.
pendingRetrybooleanSometimes 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

KeyTypeDescription
selectedEmployerIdstringThe uuid of the employer selected by the user in the search page.
selectedEmployerNamestringThe name of the employer selected by the user in the search page.

select_platform

User selected a platform

Payload

KeyTypeDescription
selectedPlatformIdstringThe uuid of the platform selected by the user in the search page.
selectedPlatformNamestringThe 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

KeyTypeDescription
platformIdstringThe uuid of the platform that the user has attempted to log in to.

login

User logged in successfully.

Payload

KeyTypeDescription
platformIdstringThe uuid of the platform that the user has logged in to.
accountIdstringThe 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)

KeyTypeDescription
actionstringOptional. Can be full_switch or partial_switch. May not be present for all platforms.
allocation.typestringOptional. This key is only present when the action is partial_switch. Can be remainder, amount, or percentage.
allocation.valuenumberOptional. This key is only present when the allocation.type is amount or percentage.

Payload (SDK v2)

KeyTypeDescription
actionstringCan be full_switch or partial_switch.
allocation.typestringOptional. This key is only present when the action is partial_switch. Can be remainder, amount, or percentage.
allocation.valuenumberOptional. 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

KeyTypeDescription
valuenumberThe value of the switch.
unitstringEither '$' 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

KeyTypeDescription
uploadedDocumentSubmittedCountnumberThe 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

KeyTypeDescription
urlstringThe 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

KeyTypeDescription
screen_namestringThe name of the screen that was encountered. See options for this key below.
selectedEmployerIdstringOptional. Only available if the screen_name is "LOGIN". The uuid of the selected employer.
selectedEmployerNamestringOptional. Only available if the screen_name is "LOGIN". The name of the selected employer.
selectedPlatformIdstringOptional. Only available if the screen_name is "LOGIN". The uuid of the selected platform.
selectedPlatformNamestringOptional. 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_nameDescription
SEARCH_DEFAULTDefault search screen after the initial intro page.
SEARCH_RESULTSResults screen when the user starts a search from the SEARCH_DEFAULT screen.
SEARCH_PLATFORM_ONLYFrom the SEARCH_RESULTS screen, the user is able to search through a list filtered for platforms only.
PROVIDER_CONFIRMATIONProvider 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.
LOGINLogin screen once the user has selected a platform or employer from search.
DD_AMOUNT_SELECTIONDirect deposit amount selection screen after the user has successfully logged in.
DD_CONFIRMATIONConfirmation screen before a direct deposit switch is performed.
JOB_SUCCESSJob success screen (e.g. direct deposit switch succeeded).
JOB_ERRORJob error screen (e.g. direct deposit switch failed).
EXIT_CONFIRMATIONExit 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!