Skip to main content

Akoya
Documentation

Customers guide

The Customers product supports two endpoints for retrieval of customer information.

The default endpoint (used in most cases as it is the most efficient), is Customer info (/customers). This endpoint returns information for the permissioned customer.

The second endpoint is Account holder information (/contacts). You will use this endpoint if it is required by specific data providers (please see the provider nuance documentation in the Data Recipient Hub, or if necessitated by your use case. By default, the response for Account Holder information includes the data elements for Customer info for the permissioned user in addition to the relationship data element, but some providers share customer data for additional account holders. Please see the provider documentation in the Data Recipient Hub.

The Customers product operates from the context of the bearer token (a.k.a. the authorized user). The Customer Info endpoint will meet your needs for use cases such as payment, identity verification, account opening, and UX personalization. It doesn’t return customer info at the account level (e.g. account holders for a joint account). Instead, it returns info for the currently-permissioned user **only**.

The Account Holders endpoint supports lending or credit decisioning use cases where you would want to determine the relationship between an account and the permissioned end-user (e.g. if they’re the primary account holder). This endpoint returns information on the permissioned account holder, and depending on the data provider, potentially account holders.

Please see this article from within the Data Recipient Hub for a list of providers that support the Account Holders endpoint. Please note that this article is only viewable from within the Hub.

The provider documentation tabs for each provider in the Data Recipient Hub also mention if the Account Holders endpoint is supported by that provider.

Results are returned in JSON in FDX format.

Example response

JSON
{
  "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": ["user@example.com"]
  }
}

Supported data elements

Name

Type

Description

customerId

string

Long-term persistent identity of the customer. This identity must be unique to the owning institution

name

object

none

name.first

string

First or given name. This data element may contain first & last name if not separated.

name.middle

string

none

name.last

string

none

name.prefix

string

Name prefix, e.g. Mr.

name.suffix

string

Generational or academic suffix

name.company

string

Company name

addresses

array[addresses]

An array of the customer's addresses

addresses.type

string

The location type of an address

addresses.line1

string

May contain full address if not separated

addresses.line2

string

none

addresses.line3

string

none

addresses.city

string

none

addresses.state

string

none

addresses.postalCode

string

none

addresses.country

string

ISO 3166 Country Code

telephones

array[telephones]

An array of the customer's telephone numbers.

telephones.number

string

none

telephones.type

string

none

telephones.country

string

Country calling codes defined by ITU-T recommendations E.123 and E.164

email

array[string]

An array of the customer's electronic mail addresses

Example response Customer Info (/customers)

JSON
{
    "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": [
            "user@example.com"
        ]
    }
}

Supported data elements

Name

Type

Description

customerId

string

Long-term persistent identity of the customer. This identity must be unique to the owning institution

name

object

none

name.first

string

First or given name. This data element may contain first & last name if not separated.

name.middle

string

none

name.last

string

none

name.prefix

string

Name prefix, e.g. Mr.

name.suffix

string

Generational or academic suffix

name.company

string

Company name

addresses

array[addresses]

An array of the customer's addresses

addresses.type

string

The location type of an address

addresses.line1

string

May contain full address if not separated

addresses.line2

string

none

addresses.line3

string

none

addresses.city

string

none

addresses.state

string

none

addresses.postalCode

string

none

addresses.country

string

ISO 3166 Country Code

telephones

array[telephones]

An array of the customer's telephone numbers

telephones.number

string

none

telephones.type

string

none

telephones.country

string

Country calling codes defined by ITU-T recommendations E.123 and E.164

email

array[string]

An array of the customer's electronic mail addresses

Example response Account holder (/contacts)

JSON
{
  "holders": [
    {
      "customerId": "1521963501",
      "name": {
        "first": "First",
        "middle": "H",
        "last": "Last"
      },
      "businessCustomer": {
        "registeredAgents": [
          {
            "first": "RAFirst",
            "middle": "I",
            "last": "RALast"
          }
        ],
        "registeredId": "111223333",
        "industryCode": {
          "type": "BCLASS",
          "code": "BC"
        },
        "domicile": {
          "country": "USA"
        }
      },
      "addresses": [
        {
          "state": "TN",
          "city": "SPRINGFIELD",
          "line1": "7572 Road Rd",
          "postalCode": "37172-6488"
        }
      ],
      "telephones": [
        {
          "number": "9585550103"
        }
      ],
      "email": [
          "user@example.com"
      ],
      "accounts": [
        {
          "accountId": "839502593",
          "relationship": "PRIMARY"
        }
      ],
      "relationship": "PRIMARY"
    }
  ]
}

Supported data elements (/contacts)

Name

Type

Description

holders

array[accountHolder]

FDX account holder, extends customer

holders.businessCustomer

object

Customers that are commercial in nature are affiliated with a business entity

businessCustomer.registeredAgents

array[nameObject]

See name object above

businessCustomer.registeredId

string

TIN or other identifier

businessCustomer.industryCode

object

none

businessCustomer.industryCode.type

string

BCLASS, BICS, GICS, MOODYS, NAICS, OTHER, SIC

businessCustomer.industryCode.code

string

Code value

businessCustomer.domicile

object

none

businessCustomer.domicile.region

string

Region of legal jurisdiction

businessCustomer.domicile.country

string

ISO 3166 country code

holders.accounts

array[account]

List of accounts related to customer

accounts.accountId

string

Account unique identifier

accounts.relationship

string

Relationship. see below

relationship

string

Type of relationship between account and holder. Suggested:

AUTHORIZED_USER, BUSINESS, FOR_BENEFIT_OF, FOR_BENEFIT_OF_PRIMARY, FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED, FOR_BENEFIT_OF_SECONDARY, FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED, FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED, POWER_OF_ATTORNEY, PRIMARY, PRIMARY_BORROWER, PRIMARY_JOINT, PRIMARY_JOINT_TENANTS, SECONDARY, SECONDARY_BORROWER, SECONDARY_JOINT, SECONDARY_JOINT_TENANTS, SOLE_OWNER, TRUSTEE, UNIFORM_TRANSFER_TO_MINOR

CTRL + K

Table of contents

TaxlotsCustomer info