# Account Owner Verification
source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md
Retrieves account ownership details (name, address, email and phone - where available) from a connected account at a financial institution. This is a premium endpoint - each successful call to this API results in a billable event.
With Account Owner Verification, you can:
1. Retrieve [account ownership details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---get-account-owner-details), including full name (required), address, email and phone. Optionally, you can send customer data to our [match account ownership details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) endpoint to receive confidence scores comparing the provided data and the account ownership details provided by a financial institution. This product provides everything you need to verify ownership of an account before originating a payment or funds transfer.
2. Return [identity insights](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta) based on the user's session and device data and powered by Mastercard's Identity Network. This product is available through either the Get Account Owner Details or the Match Account Owner Details endpoint. Note that this functionality is currently in beta and will incur additional cost. Aside from verifying account ownership, this product provides signals to validate that the user adding the account is likely the owner of that connected external account.
##### Account Opening Program for Mastercard Issuers {#content}
Issuers can opt into the Open Finance for Account Opening Program to secure and streamline the digital account opening process for Mastercard consumer and small business debit cards and general-purpose reloadable Mastercard consumer prepaid products. Participating Issuers will have access to Mastercard Open Finance's Account Owner Verification (one-time request), Account Detail Verification (one-time request) and Account Balance Check (up to 60 days) solutions, providing confidence in who their customers are, reducing content abandonment and inactivity, and decreasing non-sufficient fund (NSF) returns.
Under the program, these Open Finance services are provided as a free core benefit to Mastercard issuers when they are used to support digital account opening of an eligible Mastercard account.
Issuers who wish to participate in the Open Finance for Account Opening Program must sign an enrollment form. Download the form [here](https://w201.mastercardconnect.com/gcccic001/homememb/library/shared/Forms_Library/Forms/doc/0322.docx). Reach out to your support representative for more information.
## How It Works {#how-it-works}
1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) in the Quick Start Guide.
2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) in the Quick Start Guide.
3. Create a customer and link them to at least one account. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) in the Quick Start Guide (you will need to connect a checking and savings account using "Finbank" with the username and password "demo_rtn2").
4. Call [Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---get-account-owner-details) with a `customerId` and `accountId` to return the account ownership information; or call [Match Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) with a `customerId` and `accountId` and any values you wish to be matched (name, address, email and phone) to return the account ownership information and matching confidence scores.
Diagram account-owner
### Account Owner Data {#account-owner-data}
Many Financial Institutions (FI) include more detailed information about the account owner than just their name and address. The following data objects are available if they are provided by an FI that allow you to accurately identify the individual that you are doing business with and make informed business decisions:
* Account holders
* Addresses
* Email addresses
* Phone numbers
* Documentations (not currently in use)
Note: The Account Owner endpoints will always include at least one `holder` containing `ownerName` and `nameClassification`.
The remaining fields are optional and dependent upon the financial institution providing the data. This includes, among others: `ownerAddress` (and corresponding structured data elements), `email` (with type and primary designation) `phone` (with type), and account holder `relationship`.
At present, the `documentation` data object is not currently in use in any region. The data provided in testing environments is only for illustrative purposes.
### Name Classification {#name-classification}
The Name Classification service is built on state-of-the-art machine learning technology that provides detailed data about the account holder, which can help you make informed business decisions. The service classifies the data into one of the following `nameClassification` categories:
* Person
* Business
* Other
The `nameClassificationConfidenceScore` value provides a confidence score between 0.0 and 1.0, indicating the certainty of the accuracy of the `nameClassification` value. While you can determine your own ranges, we recommend grouping scores according to the following ranges:
| 0 - 59 | 60 - 89 | 90 - 100 |
|---------------|------------------|----------------|
| LowConfidence | MediumConfidence | HighConfidence |
Another way to interpret these scoring brackets is as follows:
* 0.9 - 1.0: High confidence.
* 0.6 - 0.89: Medium confidence.
* 0.0 - 0.59: Low confidence. Additional verification is needed (we recommend verifying other data).
### Recommendations {#recommendations}
When verifying ownership of a financial account the following best practices are recommended:
* **Name** : Only `ownerName` is required for a successful account owner response and will be included by all data providers that support this product. Many providers also provide the name value broken down to individual fields; we recommend validating the individual name fields such as `firstName` and `lastName`, and then falling back to the `ownerName` value in the event other fields are unavailable.
* **Address** : While `ownerAddress` is provided by a majority of data providers, it is not required for a successful account owner response. Many providers also provide the address value broken down to individual fields; if you choose to evaluate an account owner's address, we recommend validating the individual address fields such as `line1`, `city` and `postalCode`, and then falling back to the `ownerAddress` value in the event other fields are unavailable as well as accounting for a null address response.
* **Phone** : If provided, the `phone` number could be supplied with or without formatting, depending on the data provider. If creating a rule against this optional value, we recommend accounting for the following variations: ##########, ###-###-####, +##########, ###-###-#####, ###########, +# (###) ###-####, (###) ###-####
* **Email** : If provided, the `email` address should follow the standard format of \[username\]@\[domain name\].\[top-level domain\] such as "[username@example.com](mailto:username@example.com)". If you create a rule against this optional value, we recommend validating the format matches the standard email format.
* **Documentations** : While provided in the FDX specification and within our Sandbox environment, these data elements are not currently supplied by any data providers in production. *At this time, we do not recommend creating rules against any of the fields provided in the `documentations` section.*
Keeping the above information in mind, review the various endpoints below to determine which features you need to verify account ownership, match ownership data to your platform, or gain further identity insights on your users.
## API - Get Account Owner Details {#api---get-account-owner-details}
The latest version of our account owner product includes a response that is broken out into individually structured [data objects](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#account-owner-data-objects) identifying account holders by their name, addresses, phone numbers and emails - when provided by a connected financial institution. The response also includes a [Name Classification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#name-classification) designation that determines the "nameClassification" (person, business, etc.) for any account holders identified for the connected account.
API Reference: `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/owner`
### Testing {#testing}
We have made multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#testing-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, contact your solution engineer.
A sample Get Account Owner v3 request and response is shown below:
curl -X GET \ --url 'https://api.finicity.com/aggregation/v3/customers/{customerId}/accounts/{accountId}/owner' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}'
The response will require that `ownerName` and `nameClassification` be provided at minimum. The availability of other data elements (address, email, phone, etc.) are dependent upon institution:
```JSON
{
"holders":[
{
"relationship":"AUTHORIZED_USER",
"ownerName":"John Smith, PhD",
"firstName":"John",
"middleName":"L",
"lastName":"Smith",
"suffix":"PhD",
"nameClassification":"person",
"nameClassificationconfidencescore":0.9,
"addresses":[
{
"ownerAddress":"434 W Ascension Way Suite #200 Murray UT 84123",
"type":"Home",
"line1":"434 W Ascension Way",
"line2":"Suite #200",
"line3":"UT 84123",
"city":"Murray",
"state":"UT",
"postalCode":"84123",
"country":"USA"
}
],
"emails":[
{
"isPrimary":true,
"email":"myname@example.com",
"emailType":"Personal"
}
],
"phones":[
{
"type":"HOME",
"country":"US",
"phone":"1-801-984-4200"
}
]
}
]
}
```
## API - Match Account Owner Details {#api---match-account-owner-details}
This endpoint returns a confidence score indicating how closely the customer-provided owner data (name, address, email, and phone) matches the information retrieved from their connected financial institution during the Know Your Customer (KYC) process.
To use this endpoint, you must collect the customer's data in advance and include it in the POST request (name is a required element of the request, while providing address, email and phone is optional). Note that the response contains the institution-sourced account owner data as well as the matching confidence scores.
API Reference: `POST /account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}`
In addition we've added the ability to request optional [identity insights](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta) for a customer through this endpoint. That product includes a set of real-time identity signals assessing how account owner's information align with the user's session and device data. Note that this functionality is currently in beta and will incur additional cost.
### Testing {#testing-1}
We have made multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#testing-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your solution engineer.
A sample Match Account Owner Details request and response is shown below:
curl --location 'https://api.finicity.com/account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
"name": {
"firstName": "John",
"lastName": "Smith"
},
"address": {
"line1": "101 Test Street",
"line2": "Apt 101A",
"city": "New York City",
"state": "NY",
"country": "USA",
"postalCode": "12345",
"type": "Home"
},
"phone": "1002221234",
"email": "test@mastercard.com"
}'
The output will be similar to the base account owner, with the addition of confidence scores for each element both provided in the request and retrieved from the institution:
```JSON
{
"holders":[
{
"relationship":"PRIMARY",
"ownerName":"John Smith",
"firstName":"John",
"middleName":"K",
"lastName":"Smith",
"nameClassification":"person",
"nameClassificationconfidencescore":1.0,
"nameScores": {
"ownerName": 100,
"firstName": 100,
"lastName": 100
},
"addresses":[
{
"ownerAddress":"101 Test Street #1A New York City NY 12345",
"type":"Home",
"line1":"101 Test Street",
"line2":"#101A",
"line3":"UT 84123",
"city":"New York City",
"state":"NY",
"postalCode":"12345",
"country":"USA",
"addressScores": {
"ownerAddress": 100,
"type": 100,
"line1": 100,
"line2": 100,
"city": 100,
"state": 100,
"postalCode": 100,
"country": 100
}
}
],
"emails":[
{
"isPrimary":true,
"email":"myname@example.com",
"emailType":"Personal",
"emailScores": {
"email": 100
}
}
],
"phones":[
{
"type":"HOME",
"country":"US",
"phone":"1-100-222-1234",
"phoneScores": {
"phone": 100
}
}
]
}
]
}
```
### Scoring Process {#scoring-process}
We use a combination of string character comparison logic and a machine learning model to determine if the values provided in the request match with those provided by the customer's financial institution. We also have incorporated logic to verify against common abbreviations and designators (w : west, ave : avenue, NY : New York, apt : unit, etc.) to increase matching confidence.
A score will be produced for each value provided in the request, granted that the same data element is provided by the financial institution.
Note: The score produced for `ownerName` is generated based on the name values provided in the request (`firstName`, `lastName`, etc.) as compared to the `ownerName` provided by the financial institution.
The score produced for `ownerAddress` is generated based on the address values provided in the request (`line1`, `line2`, `city`, etc.) as compared to the `ownerAddress` provided by the financial institution or structured fields, when available.
### Score Interpretation {#score-interpretation}
Matching results are provided on a scale from 0 to 100, with a higher score indicating a higher likelihood that a match exists. The best practice would be to refer to the most specific scores as a primary check (giving preference to "firstName" and "lastName" scores over the "ownerName" score as well as "line1", "city", "postalCode", etc. scores over the "ownerAddress" score) but allowing a check to fall back on the overall score if specific values are unavailable.
Scores are provided at a granular level, allowing you to set acceptance levels based on your own risk tolerance. We recommend interpreting the scores values in buckets of pass (Match), fail (NoMatch) or needs review (PossibleMatch) as follows:
| Scores | 0 - 59 | 60 - 69 | 70 - 89 | 90 - 99 | 100 |
|-------------|---------|---------|---------------|---------|-------|
| **Name** | NoMatch | NoMatch | PossibleMatch | Match | Match |
| **Address** | NoMatch | NoMatch | PossibleMatch | Match | Match |
| **Phone** | NoMatch | N/A | N/A | N/A | Match |
| **Email** | NoMatch | N/A | N/A | N/A | Match |
Another way to interpret these scoring brackets is as follows:
* 100 = Excellent, Match (the values match exactly)
* 90 - 99 = Good, Match (the values match closely, but have some minor difference)
* 70 - 89 = Satisfactory, Match Possible (the values are similar, but may require more review)
* 60 - 69 = Mixed, Not a Match (the results are mixed, and less likely to be a match)
* 0 - 59 = Irrelevant, Not a Match (few similarities, not a match)
### Recommendations {#recommendations-1}
##### Name Matching {#name-matching}
When matching against account owner information, only the name value (`firstName` \& `lastName`) is required in the request. Based on the values included, we provide individual scores for each field returned by the financial institution (i.e. a `firstName` score and so on); additionally, an `ownerName` score is provided based on the combined name values provided in the request (`firstName` + `middleName` + `lastName` + `suffix`) matched against the `ownerName` provided in the response.
Direct users to provide their legal name to increase matching confidence against a financial institution-provided name. We recommend only sending `firstName` and `lastName` in the request, while excluding `middleName` \& `suffix`. The rate at which `middleName` and `suffix` are provided (fill rate) is not consistent among all institutions, and may decrease the matching score for `ownerName`. When reviewing scores in the response, first attempt to validate the `firstName` and `lastName` scores and then fall back to the `ownerName` score if not provided or when validating an organization name.
###### Sample Request: Person Name Example {#sample-request-person-name-example}
"name": {
"firstName": "John",
"lastName": "Smith"
}
###### Sample Request: Business Name Example {#sample-request-business-name-example}
"name": {
"ownerName": "Circus City Inc"
}
##### Address Matching {#address-matching}
If you provide an address for matching, ensure you include all address fields (`line1`, `line2`, `city`, `state`, `postalCode`, `country`) that are applicable to the user. In the response, matching scores will be returned for each individual field provided by the institution as well as against the full `ownerAddress` string (where available). Note that `ownerAddress` and individual address fields are optional in the response, and is subject to availability.
If you wish to provide this value for matching, direct your users to provide their billing or mailing address to increase matching confidence against a financial institution-provided address. When reviewing scores in the response, first attempt to validate the `line1`, `city` and `postalCode` scores (optionally, you may include the `line2` and `state` values in this) and then fall back to the `ownerAddress` score if the individual scores are not provided. Generally speaking, the `line3` value can be ignored as it is most often a reflection of the `city`, `state` and `postalCode` that will likely have been provided or can be inferred.
###### Sample Request: Example Address 1 {#sample-request-example-address-1}
"address": {
"line1": "101 Test Street",
"line2": "Apt 101A",
"city": "New York City",
"state": "NY",
"country": "USA",
"postalCode": "12345",
"type": "Home"
}
###### Sample Request: Example Address 2 {#sample-request-example-address-2}
"address": {
"line1": "102 Test Street",
"city": "New York City",
"state": "NY",
"country": "United States",
"postalCode": "123456789",
"type": "Home"
}
##### Phone \& Email Matching {#phone--email-matching}
Direct users to provide the primary mobile phone number or email address used for communication from their financial institution to increase matching confidence against a financial institution-provided `phone` or `email` value.
###### Sample Request: Example Phone \& Email {#sample-request-example-phone--email}
"phone": "1002221234",
"email": "test@mastercard.com"
## Identity Insights (Beta) {#identity-insights-beta}
Additional insight into an account holder's identity and behaviors is available through the Get Account Owner Details and Match Account Owner Details endpoints. Note that requesting identity insights will incur an additional cost - please contact your sales representative/account manager to learn more.
For Financial Institutions especially, the balance between consumer friction and fraud detection is even more acute when assessing thin-file or under-banked consumers. Risk-averse banks often treat applications as fraudulent until proven otherwise to protect against growing identity fraud, leading to poor user experiences that may drive good consumers to competitors.
With additional identity insights and predictive signals, it is possible to balance customer acquisition goals while combating fraud. These identity insights enable real-time risk assessments without disrupting potential customers. Unlike other account opening solutions, we provide dynamic data sources --- including account ownership details, device intelligence, individual attributes (PII), and predictive signals and scores --- in a single API response to enable businesses to optimize their onboarding decisioning.
These insights are provided in partnership with [Ekata Inc., a Mastercard company](https://developer.mastercard.com/identity-insights-for-accounts/documentation/). Ekata is a leader in identity validation and fraud prevention. Leveraging their capabilities, the Account Owner endpoint can provide insights about your customer's identity that can enhance your fraud protection and decisioning.
Key features of identity insights data are:
* **Account Owner Details** --- Personal information (name, email, address, phone), directly sourced from the account holder's financial institution.
* **Individual Attributes** --- High-quality licensed data from global providers to access the validity of individual attributes and how they are linked together.
* **Device Intelligence** --- Real time signals to assess device authenticity, spoofed settings, or association with past fraud across our device network.
* **Predictive Signals and Scores** --- Network and model-derived predictions to assess the potential risk of an application and inform onboarding decisions and rules.
Note: Identity insights are only available from a selection of Financial Institutions, including those which have an [OAuth connection](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md) or have otherwise been optimized through our Fast AO process to collect the owner's phone and email address. Requesting identity insights will incur an additional cost. Contact your Sales representative/Account Manager to learn more.
### Testing {#testing-2}
We have made multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#testing-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your solution engineer.
To request Identity Insights you need to include the `?withInsights=true` parameter in the request URI.
Diagram ekata-account-owner
A sample request to include identity insights is shown below:
### Get Account Owner Details {#get-account-owner-details}
curl -X GET \ --url 'https://api.finicity.com/aggregation/v3/customers/{customerId}/accounts/{accountId}/owner?withInsights=true \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}'
### Match Account Owner Details {#match-account-owner-details}
curl --location 'https://api.finicity.com/account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}?insights=true' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
"name": {
"firstName": "Test",
"lastName": "Customer"
},
"address": {
"line1": "101 Test Street",
"line2": "Apt 101A",
"city": "New York City",
"state": "NY",
"country": "USA",
"postalCode": "12345",
"type": "Home"
},
"phone": "1002221234",
"email": "test@mastercard.com"
}'
The output will be similar to the base account owner or account owner match response, with the addition of one or more optional `identityInsights` data elements as provided below:
Warning: At present, the data elements in the `device` section are currently being redesigned. New device scores and signals will replace these values in late 2025. Contact your Sales representative/Account Manager for more information.
```JSON
{
"holders": [
{
...
"identityInsights": {
"requestRefId": "be3ad617-04ad-43e1-a438-79425b6511b6",
"isEmailValid": true,
"emailFirstSeenDays": 453,
"emailDomainCreationDate": "2011-06-29T00:00:00.000Z",
"emailToName": "not found",
"ipRisk": true,
"ipRiskScore": 0.123,
"ipLastSeenDays": 15,
"ipGeolocationCountryCode": "US",
"ipGeolocationSubdivision": "Oregon",
"ipPhoneDistance": 200,
"ipAddressDistance": 210,
"isPhoneValid": true,
"phoneLineType": "mobile",
"phoneCarrier": "Vodafone UK ltd.",
"phoneCountryCode": "UK",
"phoneLastSeenDays": 42,
"phoneEmailFirstSeenDays": 54,
"phoneToName": "match",
"phoneToAddress": "match",
"addressValidityLevel": "valid",
"addressToName": "match",
"emailRisk": 0.8,
"identityRiskScore": 275,
"identityRiskReasonCode": "AA",
"deviceRiskScore": 0.45,
"deviceType": "iPhone",
"deviceBrowser": "Mobile Safari",
"devicePlatform": "iOS",
"devicePhoneEmailFirstSeen": 140,
"deviceBrowserIpTzDifference": 1000,
"deviceIpEmailFirstSeen": 365,
},
"warnings": [
"Test warnings"
],
"alerts": [
"Unable to generate IP and user insights"
]
}
}
]
}
```
### Recommendations {#recommendations-2}
The purpose of these rule recommendations is to help you use Account Owner data and Identity Insights within the appropriate workflows to meet your business objectives, such as mitigating potential fraud or increasing approvals for low risk users.
We hope these recommendations make it easier for you to get started, but we ask you to keep in mind that they are only meant to serve as a guiding light. As you begin to see data returned from the use of these signals, we suggest assessing which signals are most useful as predictors of risk and adjusting any rules to derive as much value as possible.
Rather than implementing a ruleset from the start, it may be beneficial to begin ingesting the insight signals and evaluating which values are most predictive for your particular application. Consultation services are available in a limited capacity - contact your support representative for more information.
#### Guidelines {#guidelines}
We recommend trying combinations of criteria from different rows within the same target column to create your
rules. A few things to note:
* Italicized rules tend to be the most predictive in identifying high risk users, however, we still suggest adjusting them according to your population for the greatest impact.
* We recommend trying combinations of rules from different rows to see which signals are most predictive for your use case.
* Rules in the same row (High Risk, Moderate, Low Risk) should not be used together --- pick one column and select a few signals to monitor from that ruleset.
* Combine with AND to get higher precision (more restrictive). Combine with OR to get higher recall (more approvals).
* Ultimately, adjust thresholds as you see fit - these are just guidelines.
| Signals | Stop High-Risk Rule | Moderate Rule | Pass Low-Risk Rule |
|----------------------------------|------------------------|----------------------|--------------------|
| **Scores** | | | |
| *Identity Risk Score* | \> 400 | \> 450 | \< 150 |
| *IP Risk Score* | \> 0.9 | \> 0.95 | \< 0.3 |
| *Email Risk Score* | \> 0.9 | \> 0.95 | \< 0.3 |
| *Device Risk Score* | \> 0.9 | \> 0.95 | \< 0.3 |
| **Phone Checks** | | | |
| Is Phone Valid | = False | -- | = True |
| *Phone Line Type* | != mobile | = non-fixed-voip | = mobile |
| Phone Last Seen | \< 30 or \> 365 days | \< 10 or \> 730 days | -- |
| Phone/Email First Seen | \< 30 days | = 0 days | \> 365 days |
| *Phone to Name* | != match | = no-match | = match |
| *Phone to Address* | country match/no-match | no-match | match |
| **IP Checks** | | | |
| *IP Distance from Address* | \> 100 miles | \> 1000 miles | \< 50 miles |
| *IP Distance from Phone* | \> 100 miles | \> 1000 miles | \< 50 miles |
| IP Last Seen | \< 30 or \> 365 | \< 10 or \> 730 | -- |
| **Email Checks** | | | |
| Email Domain Creation Date | within past year | today | \> 5 years |
| *Email First Seen* | \< 30 days | = 0 days | \> 365 days |
| Email to Name | != match | = no-match | = match |
| **Address Checks** | | | |
| *Address Validity Level* | != valid | = invalid | = valid |
| Address to Name | != match | = no-match | = match |
| **Device Checks** | | | |
| Device Email \& Phone First Seen | \< 30 days | = 0 days | \> 60 days |
| *Device Email \& IP First Seen* | \< 30 days | = 0 days | \> 60 days |
| *Browser IP Timezone Difference* | \> 0 | \> 0 | = 0 |
#### Moderate Rule Example: {#moderate-rule-example}
If you're formulating a rule to stop fraud with high precision, look at the criteria within the "Moderate Rule" column. Combine the bolded high-performing criteria first with an "AND" operator, then evaluate how many records in your transaction population meet this threshold. Then, assess whether the rule needs to be more restrictive by adding more AND criteria --- or less restrictive, by removing criteria.
###### Sample high-risk rule: {#sample-high-risk-rule}
IF:
(Identity Risk Score > 450) AND (Identity Network Score > 0.95) AND (Phone Match to Name = No Match)
THEN:
[Add additional verification step] OR [Reduce transfer limit] OR [Reject user action]
## Testing Profiles {#testing-profiles}
In addition to the test data provided below, we have multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#account-opening-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your implementation specialist.
The test profile holder information has been formatted as if it was a request for the Match Account Owner endpoint:
Username \& Password: profile_7000
Holder 1:
```JSON
{
"name": {
"firstName": "Homer",
"lastName": "Loanseeker"
},
"address": {
"line1": "434 W Ascension Way",
"line2": "#200",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123",
"type": "Home"
},
"phone": "9999999998",
"email": "finicitycss@gmail.com"
}
```
Username \& Password: profile_7002
Holder 1:
```JSON
{
"name": {
"firstName": "Homer",
"lastName": "Loanseeker"
},
"address": {
"line1": "434 W Ascension Way",
"line2": "#200",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123",
"type": "Home"
},
"phone": "9999999998",
"email": "finicitycss@gmail.com"
}
```
Holder 2:
```JSON
{
"name": {
"firstName": "Lorraine",
"lastName": "Loanseeker"
},
"address": {
"line1": "434 W Ascension Way",
"line2": "#200",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123",
"type": "Home"
},
"phone": "9999999998",
"email": "finicitycss@gmail.com"
}
```
Username \& Password: profile_1766
Holder 1:
```JSON
{
"name": {
"firstName": "CIRCUS CITY",
"lastName": "INCORPORATED"
},
"address": {
"line1": "123 Test Avenue",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123",
"type": "Business"
}
}
```
Username \& Password: profile_1765
Holder 1:
```JSON
{
"name": {
"firstName": "More",
"lastName": "Mechanics",
"suffix": "LLC"
},
"address": {
"line1": "123 Test Avenue",
"city": "Murray",
"state": "UT",
"country": "US",
"postalCode": "84123",
"type": "Work"
},
"phone": "8015555555",
"email": "test@test.com"
}
```
Holder 2:
```JSON
{
"name": {
"firstName": "Jimbo",
"lastName": "Macintosh"
},
"address": {
"line1": "456 Imagination Lane",
"city": "Salt Lake City",
"state": "UT",
"country": "US",
"postalCode": "84000",
"type": "Home"
},
"phone": "8015555555",
"email": "test@test.com"
}
```
Username \& Password: profile_02
Holder 1:
```JSON
{
"name": {
"firstName": "HOMER",
"lastName": "LOANSEEKER"
},
"address": {
"line1": "123 FAKE STREET",
"city": "OGDEN",
"state": "UT",
"country": "US",
"postalCode": "84401",
"type": "Home"
}
}
```
Username \& Password: profile_03
Holder 1 \& 2:
```JSON
{
"name": {
"firstName": "PATRICK",
"middleName": "LORRAINE",
"lastName": "PURCHASER"
},
"address": {
"line1": "7195 BELMONT ST.",
"city": "PARLIN",
"state": "NJ",
"country": "US",
"postalCode": "08859",
"type": "Home"
}
}
```
Note: If there are multiple holders on a legacy connection (not enabled for OAuth), the names may be provided together as a single holder. In this case, the ownerName is returned as "PATRICK \& LORRAINE PURCHASER". Presently, only a single owner can be sent to be matched per request Username \& Password: profile_05
Holder 1 \& 2:
```JSON
{
"name": {
"firstName": "JOHN",
"lastName": "HOMEOWNER"
},
"address": {
"line1": "123 Test ST.",
"city": "SPRINGFIELD",
"state": "VA",
"country": "US",
"postalCode": "221621058",
"type": "Home"
}
}
```
Note: If there are multiple holders on a legacy connection (not enabled for OAuth), the names may be provided together as a single holder. In this test case, the ownerName is returned as "JOHN HOMEOWNER MARY HOMEOWNER". Presently, only a single owner can be sent to be matched per request.
## Common Errors {#common-errors}
In the event that we encounter an issue at any point while requesting Account Owner Verification, you will be informed by a response containing the error `code` and corresponding `message` explaining the issue and any possible resolution steps.
While some commonly encountered errors are listed below, be sure to refer to our [Error Code](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) documentation page for an exhaustive list of potential errors and click on the link to review documentation for a specific code.
| Code | HTTP Status | Brief Description |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------|
| [102](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#102) | 500 | We're unable to establish a connection to your financial institution. |
| [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) | 500 | Invalid login credentials. |
| [106](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#106) | 500 | User action required at financial institution. |
| [170](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#168-170-178-180-and-184) | 500 | An error occurred in the financial institution connection. |
| [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) | 500 | Missing or incorrect MFA answer. |
| [197](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#168-170-178-180-and-184) | 500 | An error occurred in the financial institution connection. |
| [265](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#265) | 500 | Owner information not available. |
| [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | 500 | The account is currently being aggregated. |
| [910](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#910) | 500 | Financial institution connection is currently broken and currently being worked on. |
| [946](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#946) | 500 | The token has been accepted but no record has been returned from the institution for the request. This may be due to account closure. |
| [947](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#947) | 500 | Your token is invalid or has expired, Please re-authenticate. |
| [960](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#960) | 500 | Electronic Statement is not available for the requested account. |
| [961](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#961) | 500 | Enrollment Required for Paperless Statement/Activate Electronic Statement. |
| [973](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#973) | 500 | The user is not authorized for the requested resource or online access. |
| [975](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#975) | 500 | Bank has blocked access to resources for the user concerning security reasons. |
| [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#979-980-982-and-983) | 500 | An error occurred in the financial institution connection. |
| [13002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#13002) | 404 | The Statement asset for this account was not found. |
| [19000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#19000) | 500 | The Account Owner Verification service experienced an internal error. |
| [38003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38003) | 404 | The customer does not have the given account. This may be due to the account being deleted. |
| [44000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#44000) | 202 | Invalid App key. |
## Fast AOV {#fast-aov}
Fast AOV is an optimized Account Owner Verification solution that enables faster
responses to [Get Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---get-account-owner-details) or
[Match Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) requests.
It works by caching the required data on our server for up to 4 days for faster retrieval. In many cases, it also provides
richer ownership data, such as an owner's email address and phone number.
When Fast AOV is enabled, we proactively fetch the account owner details
during the account linking process. This reduces latency and helps
prevent some data aggregation errors.
Fast AOV is offered at no additional charge.
By default, we enable Fast AOV when you create a new production project
and you are using account owner verification services.
Fast AOV may not be right for all projects and is not supported by all institutions.
Speak with your Account Manager about enabling or opting out of Fast AOV. Enabling the
service for your project can take 2 to 5 business days.
The following sequence diagram shows how Fast AOV proactively
caches routing data during the account linking process:
Diagram account-owner-cached
### Financial Data Exchange (FDX) {#financial-data-exchange-fdx}
The [Financial Data Exchange (FDX)](https://financialdataexchange.org/) is dedicated to unifying standards for secure and convenient access to user-permissioned financial data sharing throughout the financial services industry. The Get Account Owner v3 API is aligned with the [FDX API 5.0 standards](https://www.financialdataexchange.org/FDX/FDX/News/Press-Releases/Financial_Data_Exchange_Releases_FDX_API_5.0.aspx).
FDX is currently working with more than 30 different working groups and task forces involved in defining standards and improving increased access and performance.
### Get Account Owner v1 (To be Deprecated in 2026) {#get-account-owner-v1-to-be-deprecated-in-2026}
This is a historical version of the Get Account Owner endpoint; new features and enhancements are being added to the v3 endpoint (Get Account Owner Details).
The Get Account Owner v1 endpoint retrieves only the names and address for a customer's account from a financial institution. The `ownerName` and `ownerAddress` parameters are returned with multiple values present within the same, pipe-delimited response object.
A sample Get Account Owner v1.0 response:
```JSON
{
"ownerName": "John Smith | Jane Smith",
"ownerAddress": "APT C 5600 S SPRINGFIELD GARDENS CIR SPRINGFIELD, VA 22162-1058"
}
```
API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/owner`