DOCUMENTATION
Guides
Recipient login

Account ownership validation use case

Suggest Edits

Existing methods of account ownership validation rely on basic username and password authentication. Usernames and passwords are one of the most vulnerable areas in consumer security and subject to phishing and direct hacking attempts. Compromised credentials are the most common avenue to account takeover and fraudulent representation of account ownership.

Akoya’s Customers product offers a higher level of account ownership validation. You use Akoya’s API to retrieve consumer permissioned information directly from the financial institution. Data elements such as first name, last name, mailing address, e-mail address, or phone number can be used as part of a validation process. You can compare this user information retrieved from the linked external account with what you have captured directly from the end user.

The comparison process can data elements as part of a scoring algorithm comparing user-provided information with the information on file at the financial institutions. This allows data recipients to identify and flag fraud attempts during know your customer processes or whenever fraud is suspected.

For more information, see the blog post The Expansion of Account Ownership Validation Methods.

Prerequisites

The API calls require you to have the account holder’s consent. Each data call requires the end-user’s associated id token.

1. Retrieve customer info

The customer info endpoint (/customers) response returns information about the end user that you can use as data points to validate account ownership. The specific end user is identified with the id_token used for the Akoya API call. The id_token is created with the authorization code generated when the user consents to sharing their data.

Make the GET request customers/{version}/{providerId}/current

  • The {version} parameter is the Akoya major version number. Use v2.
  • The {providerId} parameter is the shortened version of the bank data provider name, example, mikomo for Mikomo, our fictional data provider. You can find the providerId for each bank listed under the Data providers tab of the Data Recipient Hub.

Retrieve customer info curl example

curl --request GET \
     --url https://sandbox-products.ddp.akoya.com/customers/v2/mikomo/current \
     --header 'accept: application/json'
     --header 'authorization: Bearer <id_token>'

2. Find data elements for the validation process

The API response contains data elements for the end user, such as first name, last name, mailing address, e-mail address, and phone number. Compare these data elements from the Akoya endpoint against the data elements submitted by the end user. Developers often implement a scoring algorithm to facilitate the comparison and flag possible fraud.

Customer info results example

{
    "customer": {
        "customerId": "1521963501",
        "name": {
            "last": "Last",
            "first": "First",
            "middle": "H"
        },
        "telephones": [
            {
                "number": "9585550103"
            }
        ],
        "addresses": [
            {
                "state": "TN",
                "city": "SPRINGFIELD",
                "line1": "7572 Road Rd",
                "postalCode": "37172-6488"
            }
        ],
        "email": [
            "[email protected]"
        ]
    }
}

Alternative retrieval of customer information

Some data providers do not support the default customer info endpoint. Use the below procedure and the account holder information endpoint for these providers.

Retrieve account information

The account information endpoint is a standalone endpoint that supplies useful account information. You need to retrieve a list of available accounts permissioned by the account holder from this endpoint.

Make the GET request /accounts-info/{version}/{providerId}

  • The {version} parameter is the Akoya major version number. Use v2.
  • The {providerId} parameter is the shortened version of the bank data provider name, example, mikomo for Mikomo, our fictional data provider. You can find the providerId for each bank listed under the Data providers tab of the Data Recipient Hub.

Retrieve account information curl example

curl --request GET \
 --url https://sandbox-products.ddp.akoya.com/accounts-info/v2/mikomo?accountIds=%3AaccountId \
 --header 'accept: application/json' \
 --header 'authorization: Bearer <id_token>'

Find the accountId

From the results of the retrieve account information call, find the the accountId of the selected account. This is the key for retrieving the customer information data elements.

Account information results example

{
 "depositAccount": {
 "accountId": "g833202fb0866d0ad83472c429",
 "accountType": "CHECKING",
 "accountNumberDisplay": "xxxxxxxx0071",
 "currency": {
 "currencyCode": "USD"
 },
 "description": "Checking Plus",
 "fiAttributes": [
.......

Request account holder information

The account holder information endpoint (/contacts) response returns information about the end user that you can use as data points to validate account ownership. This API call uses the accountId to designate the end user. It is based on FDX 5.2.1.

Make the GET request contacts/{version}/{providerId}/{accountId}

  • The {version} parameter is the Akoya major version number. Use v2.
  • The {providerId} parameter is the shortened version of the bank data provider name, example, mikomo for Mikomo, our fictional data provider. You can find the providerId for each bank listed under the Data providers tab of the Data Recipient Hub.
  • You retrieved the {accountId} with the retrieve account information call.

Retrieve account holder information example

curl --request GET \
     --url https://sandbox-products.ddp.akoya.com/contacts/v2/mikomo/1234 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <id_token>'

Find data elements for the validation process

The API response contains data elements for the end user, such as first name, last name, mailing address, e-mail address, and phone number. Compare these data elements from the Akoya endpoint against the data elements submitted by the end user. Developers often implement a scoring algorithm to facilitate the comparison and flag possible fraud.

Retrieve account holder information results example

{
    "customer": {
        "customerId": "1521963501",
        "name": {
            "last": "Last",
            "first": "First",
            "middle": "H"
        },
        "telephones": [
            {
                "number": "9585550103"
            }
        ],
        "addresses": [
            {
                "state": "TN",
                "city": "SPRINGFIELD",
                "line1": "7572 Road Rd",
                "postalCode": "37172-6488"
            }
        ],
        "email": [
            "[email protected]"
        ]
    }
}

Need help?

Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.

Looking for provider nuance documentation?

All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.

Still stuck?

For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.

Updated 4 months ago