# Data Connect User Events
source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md

User events provide full visibility into the customer's actions while they're interacting with the Connect Data Connect Lite, or Data Connect Fix applications (apps). These events are compatible with analytics tools, allowing you to build web analytics dashboards to evaluate conversions, success rates, and error rates.

## AddAccounts {#addaccounts}

|    Name     |                    Application Support                     |                     Description                     |
|-------------|------------------------------------------------------------|-----------------------------------------------------|
| AddAccounts | Data Connect Full / Data Connect Lite / Instant Onboarding | Sent when a customer attempt to add their accounts. |

This event is sent two times. The first event is sent when the customer attempts to add their bank accounts. The return includes:

* A null value for the `success`, `accounts`, and `errorCode` fields.
* The second event sent provides the details about the attempt.

The customer successfully added their accounts if:

* `accounts` = populated
* `success` = true
* `errorCode` = null
The customer failed to add their accounts if:

* `accounts` = null
* `success` = false
* `errorCode` = populated
Note: If the first event is received, but the second event never arrives, then the customer ended the attempt to add accounts before Data Connect could successfully add the accounts.

**Example response (first event):**

```JSON
{
  "action": "AddAccounts",
  "institutionId": 123,
  "institutionLoginId": null,
  "accounts": null,
  "accountIds": [],
  "success": null,
  "errorCode": null
}
```

**Example response (second event success):**

```JSON
{
  "action": "AddAccounts",
  "institutionId": 123,
  "institutionLoginId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": null
}
```

**Example response (second event fail):**

```JSON
{
  "action": "AddAccounts",
  "institutionId": 123,
  "institutionLoginId": null,
  "accounts": null,
  "accountIds": [],
  "success": false,
  "errorCode": 500
}
```

## CredentialedPayrollAccountConnection {#credentialedpayrollaccountconnection}

|                 Name                 | Application Support |                                 Description                                  |
|--------------------------------------|---------------------|------------------------------------------------------------------------------|
| CredentialedPayrollAccountConnection | Data Connect Full   | Sent when the customer completes the add credentialed payroll accounts flow. |

**Example response:**

```JSON
{
  "action": "CredentialedPayrollAccountConnection",
  "institutionId": 123,
  "accounts": 1,
  "payrollAccountIds": [
    "0193d0ab-9473-3e6d-58d2-039d6dafda45"
  ],
  "customerId": 12345,
  "success": true,
  "errorCode": null
}
```

## DisplayAlert {#displayalert}

|     Name     |                              Application Support                              |                                                             Description                                                              |
|--------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| DisplayAlert | Data Connect Full / Data Connect Lite / Data Connect Fix / Instant Onboarding | Sent when a customer receives an alert within a Data Connect session. The return includes: * The error code * The error code message |

Note: These fields are only sent if an alert occurs for an FI:

* `institutionId`
* `institutionName`

**Example response:**

```JSON
{
  "action": "DisplayAlert",
  "alertType": "ERROR",
  "title": "Error",
  "message": "An error occurred.",
  "errorCode": 500,
  "data": {
    "details": "Invalid input"
  }
}
```

## End {#end}

| Name |                   Application Support                   |                             Description                             |
|------|---------------------------------------------------------|---------------------------------------------------------------------|
| End  | Data Connect Full, Data Connect Fix, Instant Onboarding | Sent when the Instant Onboarding session terminates for any reason. |

This is the terminal event for every session. It fires regardless of whether the session ended in success, cancellation, or error. Use the code and reason fields to determine the outcome.
The session completed successfully if:

* `code` = 200
* `reason` = "complete"
* Event arrives in `onDone` callback
The session was cancelled by the user if:

* `code` = 100
* `reason` = "exit"
* Event arrives in `onCancel` callback
The session timed out if:

* `code` = 1440
* `reason` = "timeout"
* Event arrives in `onCancel` callback
The session ended in error if:

* `code` = 500
* `reason` = "error"
* Event arrives in `onError` callback
Note: Use this event to determine when to clean up your session state. The `ttl` field indicates when the session data will expire.

##### Fields: {#fields}

|   Field    |  Type  |                           Description                            |
|------------|--------|------------------------------------------------------------------|
| action     | string | Always `End`                                                     |
| reason     | string | `complete`, `exit`, `timeout`, or `error`                        |
| code       | number | `200` (success), `100` (cancel), `1440` (timeout), `500` (error) |
| customerId | string | The Mastercard Open Banking customer ID                          |
| partnerId  | string | Your partner ID                                                  |
| timestamp  | string | Unix timestamp (ms) when the session ended                       |
| ttl        | string | Unix timestamp (ms) when session data expires                    |
| experience | string | Experience configuration ID                                      |
| sessionId  | string | Unique session identifier                                        |
| type       | string | Always `instant-onboard`                                         |
| product    | string | Product type (for example, `aggregation`)                        |

**Example response (success):**

```json
{
  "action": "End",
  "reason": "complete",
  "customerId": "7003898270",
  "partnerId": "2445584362351",
  "timestamp": "1755797900000",
  "ttl": "1755808700000",
  "experience": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "6e5bb1bb17cd185926799d167a66dc6bf299c726c907ca1056416861cd1e8962",
  "code": 200,
  "type": "instant-onboard",
  "product": "aggregation"
}
```

## FixMfaAttempt {#fixmfaattempt}

|     Name      | Application Support |                        Description                        |
|---------------|---------------------|-----------------------------------------------------------|
| FixMfaAttempt | Data Connect Fix    | Sent when a customer attempts to answer an MFA challenge. |

This event is sent two times. The first event is sent when the customer attempts to answer an MFA challenge question while signing in to their bank. The return includes:

* A null value for the `success`, `accounts`, and `errorCode` fields.

A second event sent provides the details about the attempt.
The customer successfully signed in to their accounts if:

* `accounts` = populated
* `success` = true
* `errorCode` = null
The customer encountered another MFA challenge if:

* `accounts` = null
* `success` = true
* `errorCode` = null
The customer failed to sign in to their accounts if:

* `success` = false
* `errorCode` = populated

**Example response (first event):**

```JSON
{
  "action": "FixMfaAttempt",
  "institutionId": 123,
  "institutionLoginId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": null,
  "errorCode": null
}
```

**Example response (second event success):**

```JSON
{
  "action": "FixMfaAttempt",
  "institutionId": 123,
  "institutionLoginId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": null
}
```

**Example response (second event fail):**

```JSON
{
  "action": "FixMfaAttempt",
  "institutionId": 123,
  "institutionLoginId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": false,
  "errorCode": 185
}
```

## FixSignInAttempt {#fixsigninattempt}

|       Name       | Application Support |                                        Description                                        |
|------------------|---------------------|-------------------------------------------------------------------------------------------|
| FixSignInAttempt | Data Connect Fix    | Sent when a customer tries attempts to sign in when fixing a connection to their account. |

This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes:

* A null value for the `success`, `accounts`, and `errorCode` fields.

A second event sent provides the details about the attempt.
The customer successfully fixed the sign in for the account if:

* `accounts` = populated
* `success` = true
* `errorCode` = null
The customer encountered an MFA challenge if:

* `accounts` = null
* `success` = true
* `errorCode` = null
The customer failed to fix the sign in for their account if:

* `success` = false
* `errorCode` = populated
Note: If the first event is received, but the second event never arrives, then the customer ended the attempt to fix their sign-in before Data Connect could successfully connect to the FI.

**Example response (first event):**

```JSON
{
  "action": "FixSignInAttempt",
  "institutionId": 456,
  "institutionLoginId": 789,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": null,
  "errorCode": null
}
```

**Example response (second event success):**

```JSON
{
  "action": "FixSignInAttempt",
  "institutionId": 456,
  "institutionLoginId": 789,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": null
}
```

**Example response (second event fail):**

```JSON
{
  "action": "FixSignInAttempt",
  "institutionId": 456,
  "institutionLoginId": 789,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": false,
  "errorCode": 103
}
```

## Initialize {#initialize}

|    Name    |                    Application Support                    |                              Description                              |
|------------|-----------------------------------------------------------|-----------------------------------------------------------------------|
| Initialize | Data Connect Full / Data Connect Fix / Instant Onboarding | Sent when a user starts a Data Connect or Instant Onboarding session. |

**Example response:**

```JSON
{
   "action": "Initialize",
   "customerId": 12345,
   "partnerId": 67890,
   "timestamp": 1717132800000,
   "ttl": 1717140000000,
   "type": "full",
   "experience": "550e8400-e29b-41d4-a716-446655440000",
   "secondaryDataInput": "Last4SSN",
   "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4",
   "product": "aggregation",
   "borrowerType": "primary"
}
```

## LaunchOAuth {#launchoauth}

|    Name     |          Application Support           |                       Description                       |
|-------------|----------------------------------------|---------------------------------------------------------|
| LaunchOAuth | Data Connect Full / Instant Onboarding | Sent when the customer opens an OAuth window for an FI. |

See [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md).
Note: If no other OAuth events are received after this event, then the customer most likely closed the OAuth window.

**Example response:**

```JSON
{
  "action": "LaunchOAuth",
  "institutionId": 789,
  "success": true,
  "errorCode": null
}
```

## LaunchCredentialedPayrollPopUp {#launchcredentialedpayrollpopup}

|              Name              | Application Support |                                       Description                                       |
|--------------------------------|---------------------|-----------------------------------------------------------------------------------------|
| LaunchCredentialedPayrollPopUp | Data Connect Full   | Sent when the customer launches the credentialed payroll account connection experience. |

**Example response:**

```JSON
{
  "action": "LaunchCredentialedPayrollPopUp",
  "institutionId": 123,
  "accounts": 1,
  "customerId": 1013916100,
  "success": true,
  "errorCode": null
}
```

## MfaAttempt {#mfaattempt}

|    Name    |                              Application Support                              |                         Description                         |
|------------|-------------------------------------------------------------------------------|-------------------------------------------------------------|
| MfaAttempt | Data Connect Full / Data Connect Lite / Data Connect Fix / Instant Onboarding | Sent when the customer attempts to answer an MFA challenge. |

This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes:

* A null value for the `success`, `accounts`, and `errorCode` fields.

A second event sent provides the details about the attempt.
The customer successfully signed in to their accounts if:

* `accounts` = populated
* `success` = true
* `errorCode` = null
The customer encountered another MFA challenge if:

* `accounts` = null
* `success` = true
* `errorCode` = null
The customer failed to sign in to their accounts if:

* accounts= null
* success= false
* errorCode= populated

**Example response (first event):**

```JSON
{
  "action": "MfaAttempt",
  "institutionId": 123,
  "accounts": null,
  "accountIds": [],
  "success": null,
  "errorCode": null
}
```

**Example response (second event success):**

```JSON
{
  "action": "MfaAttempt",
  "institutionId": 123,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": null
}
```

**Example response (second event fail):**

```JSON
{
  "action": "MfaAttempt",
  "institutionId": 123,
  "accounts": null,
  "accountIds": [],
  "success": null,
  "errorCode": 185
}
```

## OAuthAddAccounts {#oauthaddaccounts}

|       Name       |          Application Support           |                            Description                             |
|------------------|----------------------------------------|--------------------------------------------------------------------|
| OAuthAddAccounts | Data Connect Full / Instant Onboarding | Sent when the customer attempts to add an OAuth account for an FI. |

See [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md).

**Example response:**

```JSON
{
  "action": "OAuthAddAccounts",
  "institutionId": 123,
  "institutionLoginId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": null
}
```

## OAuthSignInAttempt {#oauthsigninattempt}

|        Name        |          Application Support           |                                Description                                |
|--------------------|----------------------------------------|---------------------------------------------------------------------------|
| OAuthSignInAttempt | Data Connect Full / Instant Onboarding | Sent when the customer attempts to sign in to an OAuth account for an FI. |

See [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md).

**Example response:**

```JSON
{
  "action": "OAuthSignInAttempt",
  "institutionId": 456,
  "success": true,
  "errorCode": null
}
```

## RemoveAccounts {#removeaccounts}

|      Name      |          Application Support           |                     Description                      |
|----------------|----------------------------------------|------------------------------------------------------|
| RemoveAccounts | Data Connect Full / Instant Onboarding | Sent when a customer tries to remove their accounts. |

This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes:

* A null value for the `success`, `accounts`, and `errorCode` fields.

A second event is sent with the results about the customer's attempt to remove their accounts:

* Successfully removes accounts
* Failed to remove accounts

Note: If the first event is received, but the second event never arrives, then the customer ended the attempt to remove their accounts before Data Connect could successfully remove them.

**Example response (first event):**

```JSON
{
  "action": "RemoveAccounts",
  "institutionId": 123,
  "institutionLoginId": null,
  "accounts": null,
  "accountIds": [],
  "success": null,
  "errorCode": null
}
```

**Example response (second event success):**

```JSON
{
  "action": "RemoveAccounts",
  "institutionId": 123,
  "institutionLoginId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": null
}
```

**Example response (second event fail):**

```JSON
{
  "action": "RemoveAccounts",
  "institutionId": 123,
  "institutionLoginId": null,
  "accounts": null,
  "accountIds": [],
  "success": false,
  "errorCode": 500
}
```

## SearchInstitutions {#searchinstitutions}

|        Name        |          Application Support           |             Description              |
|--------------------|----------------------------------------|--------------------------------------|
| SearchInstitutions | Data Connect Full / Instant Onboarding | Sent when a user searches for an FI. |

The return includes:

* The customer's query search words.
* The number of matching search results.
* The number of times the customer attempted to search.

Note: The event is only sent if this condition occurs: at least three letters are typed and the customer pauses after typing for 300 ms.

**Example response:**

```JSON
{
  "action": "SearchInstitutions",
  "searchTerm": "Bank of America",
  "resultCount": 5
}
```

## SelectInstitution {#selectinstitution}

|       Name        |          Application Support           |                     Description                     |
|-------------------|----------------------------------------|-----------------------------------------------------|
| SelectInstitution | Data Connect Full / Instant Onboarding | Sent when the customer selects an FI to sign in to. |

The return includes:

* The institution ID the customer selected.
* If the FI is supported for the product.   

**Example response:**

```JSON
{
  "action": "SelectInstitution",
  "institutionId": 123,
  "supported": true
}
```

## SessionTimeout {#sessiontimeout}

|      Name      |                              Application Support                              |                           Description                           |
|----------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------|
| SessionTimeout | Data Connect Full / Data Connect Lite / Data Connect Fix / Instant Onboarding | Sent when a customer's session has timed out due to inactivity. |

**Example response:**

```JSON
{
  "action": "SessionTimeout",
  "customerId": 12345,
  "partnerId": 67890,
  "timestamp": 1717132800000,
  "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4"
}
```

## SignInAttempt {#signinattempt}

|     Name      |          Application Support           |                       Description                       |
|---------------|----------------------------------------|---------------------------------------------------------|
| SignInAttempt | Data Connect Full / Instant Onboarding | Sent when a customer attempts to sign in to an account. |

This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes:

* A null value for the `success`, `accounts`, and `errorCode` fields.

A second event sent provides the details about the attempt.
The customer successfully signed in to their accounts if:

* `accounts` = populated
* `success` = true
* `errorCode` = null
The customer encountered an MFA challenge if:

* `accounts` = null
* `success` = true
* `errorCode` = null
The customer failed to sign in to their accounts if:

* `accounts` = null
* `success` = false
* `errorCode` = populated
Note: If the first event is received, but the second event never arrives, then the customer ended the attempt before Data Connect successfully connected to the FI.

**Example response (first event):**

```JSON
{
  "action": "SignInAttempt",
  "institutionId": 456,
  "accounts": null,
  "accountIds": [],
  "success": null,
  "errorCode": null
}
```

**Example response (second event success):**

```JSON
{
  "action": "SignInAttempt",
  "institutionId": 456,
  "accounts": 5,
  "accountIds": [
    "7079115306",
    "7079115307",
    "7079115308",
    "7079115309",
    "7079115310"
  ],
  "success": true,
  "errorCode": 0
}
```

**Example response (second event fail):**

```JSON
{
  "action": "SignInAttempt",
  "institutionId": 456,
  "accounts": null,
  "accountIds": [],
  "success": false,
  "errorCode": 103
}
```

## SubmitAccounts {#submitaccounts}

|      Name      |          Application Support           |                        Description                        |
|----------------|----------------------------------------|-----------------------------------------------------------|
| SubmitAccounts | Data Connect Full / Instant Onboarding | Sent when the customer attempts to submit their accounts. |

The return includes:

* The accounts

<br />

This user event indicates:

* The customer attempted to submit their accounts.
* The account number if the customer's attempt to submit accounts was successful.

<br />

**Example response:**

```JSON
{
  "action": "SubmitAccounts",
  "customerId": 12345,
  "partnerId": 67890,
  "timestamp": 1717132800000,
  "ttl": 1717140000000,
  "type": "full",
  "experience": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4",
  "product": "aggregation"
}
```