# Events

All events will have the following format, that includes a type and timestamp on the object. Certain events have a payload property with more event details. See [#event-payloads](#event-payloads "mention") for more details.

```json
{
   type: 'payscore/incomeVerification/loaded',
   timestamp : "2011-12-19T15:28:46.493Z",
   payscore: true
   payload?: Object;
}
```

<table><thead><tr><th width="513.6015625">Event Type</th><th width="442.14453125">Description</th></tr></thead><tbody><tr><td><code>payscore/incomeVerification/loaded</code></td><td>Triggers when the widget loads.<br>Can be used to provide your own “widget loading” experience prior to widget mount.</td></tr><tr><td><code>payscore/incomeVerification/widgetClosed</code></td><td>Triggers when the embedded widget is manually closed by the applicant.</td></tr><tr><td><code>payscore/incomeVerification/started</code></td><td>Triggers when the applicant interacts with the workflow for the first time.</td></tr><tr><td><code>payscore/incomeVerification/institutionSelected</code></td><td>Triggers when an applicant selects a bank, payroll provider, or employer.</td></tr><tr><td><code>payscore/incomeVerification/institutionConnected</code></td><td>Triggers when an applicant successfully connects to their bank, payroll provider, or employer.</td></tr><tr><td><code>payscore/incomeVerification/documentUploaded</code></td><td>Triggers when an applicant uploads a document.</td></tr><tr><td><code>payscore/incomeVerification/completed</code></td><td>Triggers when the applicant completes the workflow, fills out the feedback (or skips it), and submits the report. The widget should be closed after this event.</td></tr></tbody></table>

## Event Payloads

Certain events contain payloads of data pertaining to the event that occurred. When using typescript, you can use the generic `PayscoreBaseEvent` type to narrow the payload value for your object.

**Payload resolution:**

<table data-header-hidden><thead><tr><th>Event Type</th><th>Payload</th></tr></thead><tbody><tr><td><code>payscore/incomeVerification/institutionConnected</code></td><td><pre class="language-ts"><code class="lang-ts">{ 
  institution: string;
  method: IncomeVerificationMethod
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/institutionSelected</code></td><td><pre><code>{ 
  institution: string;
  method: IncomeVerificationMethod
}
</code></pre></td></tr></tbody></table>

**Example:**

```ts
const onEvent = (event: PayscoreBaseEvent, widget: IncomeVerificationWidget) => {
    const { type, timestamp } = event;

    switch (type) {
        case PayscoreWidgetEventType.InstitutionConnected: {
            // Cast to narrow payload
            const { payload } = event as PayscoreBaseEvent<PayscoreWidgetEventType.InstitutionConnected>;
            console.log(payload.institution);
            break;
        }
    }
};
```

Pass the event type as the generic argument and TypeScript will enforce the correct `payload` shape — or `undefined` for event types that carry no payload.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payscore.com/embedded-widget/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.