Migrating to Akoya API v2

📘

Notice

Akoya has launched the v2 of its endpoints (in beta through October 2022). This document is intended to help data recipients currently using v1 to migrate to v2.

Migration considerations

Overview

Changes you may need to make to migrate to Akoya API v2:

• Versioning support. Akoya limits breaking changes to major API versions. To reduce the need for large, breaking-change updates, Akoya will continue to improve its products by releasing minor updates on a continual basis. These minor updates are non-breaking, backward-compatible improvements. When migrating to Akoya API v2, please plan for these minor version updates and implement in a way to allow for these non-breaking changes. Please see the versioning guide for more details.
• Transaction pagination. With Akoya API v1, paging through transaction data could require different implementations per provider. To standardize paging, we’ve introduced link-based pagination. All paging implementations from Akoya API v1 will need to be migrated to using Akoya-generated links instead. For more information, see: Link-based pagination.
• Endpoint path names. Akoya has introduced products to allow a more streamlined approach to data access. To support our new products, all new endpoints include the Akoya version in the path and no longer include the FDX version. We’ve also named the endpoints to more closely coincide with our products rather than using a single FDX /accounts endpoint. For example, if your use case requires balance data, the endpoint will now be: https://products.ddp.akoya.com/balances/v2/. For a full list of endpoints, see: [Endpoint summary] (#endpoint-summary "Endpoint summary")
• Data element support.
  • In the near future, to support our new products, the following data elements will no longer be available through the Akoya API v1 /accounts endpoint. However, these data elements will be available in the Payments product:
    • accountNumber
    • routingTransitNumber
  • Data elements available through the Akoya API v1 /accounts details calls will now be available through either the Accounts info, Balances, or Investment products. Please consider your use case to determine which products will continue to provide the data your app requires.
    As a general guide, detailed data for all account categories except investment accounts can be retrieved through the Balances product. If you need more detailed investment data, please consider the Investments product instead.
• FDX lightweight call. The new /accounts-info endpoint will replace the FDX accounts lightweight call. Differentiating between details and lightweight with a parameter using the /accounts endpoint is no longer necessary.

While the list above covers the most significant migration considerations, please read the full details below to determine if other changes may impact your app.

Update details

Current support

🚧

Akoya API v1 sunset in sandbox

The Akoya API v1 data endpoints have been retired in sandbox. Please see this changelog post for further details.

• Akoya API v1, modeled after FDX’s “Financial Data Exchange (FDX) v4.1”
• Akoya API v2, modeled after FDX’s “Financial Data Exchange (FDX) v4.5” where possible with a few variations specific to Akoya

Akoya API v2

• Data elements follow FDX 4.5 guidelines where possible.

  • Exception: Akoya does not support annuityAccount inheriting from accounts.

• All new endpoints include the Akoya version in the path and no longer include the FDX version.

  • Example: https://products.ddp.akoya.com/balances/v2/

• Link-based pagination standardization.

• Akoya endpoints

  • /accounts-info/v2/{providerId}/

  • /accounts/v2/{providerId}/

  • /balances/v2/{providerId}/

  • /transactions/v2/{providerId}/{accountId}

  • /payments/v2/{providerId}/{accountId}/payment-networks

  • /customers/v2/{providerId}/current

  • /statements/v2/{providerId}/{accountId}

  • /statements/v2/{providerId}/{accountId}/{statementId}

Endpoint summary

Endpoint details:

Accounts Info (/accounts-basic/v2/{providerId}/) New

• A list of accounts with basic info data
• Replaces the FDX accounts lightweight concept
• Typical use: populating an account selection screen for the end-user or high-level information for a list of accounts
• Responses include
  • A basic version of account info data elements such as accountType, productName, status, or currency.
  • Returns multiple accounts or query specific accounts
  • Supports all account categories

Balances (/balances/v2/{providerId}/) New

• Account info and balances data
• Typical use: displaying balance information to the end-user or conducting balance checks before initiating a payment
• Responses include
  • Both account info and balances data elements such as accountType, currency, balanceAsOf, availableBalance, currentBalance, creditLine, or availableCredit.
  • Returns multiple accounts or query specific accounts
  • Supports all account categories

Investments (/accounts/v2/{providerId}/) New

• A comprehensive version of account info, balances, and investments data
• Typical use: retrieve a comprehensive view of all account information for PFM or Wealth Management
• Responses include
  • a comprehensive version of account info, balances, and investments data elements such as marginBalance, availableCashBalance, holdings (e.g., holdingType, symbol, units), or contribution (e.g., employerYearToDate, employeeYearToDate).
  • Returns multiple accounts or query specific accounts
  • Supports all account categories

Transactions (/transactions/v2/{providerId}/{accountId}) Updated

• Added ability to page transaction results in a standardized way
• The versioning has been updated to /v2
• all 200 responses will return a pageLinks object with links (when applicable) for paging backward and forward in results (see: link to pagination documentation)
• Responses include
  • From a single account, a list of transactions data elements such as transactionId, postedTimestamp, description, category, amount, or transactionType.
  • Supports all applicable account categories

Payment Networks (/payments/v2/{providerId}/{accountId}/payment-networks) No Changes

• No changes to the data elements
• The versioning has been updated to /v2
• Responses include
  • Payment network related data elements such as bankId (i.e., routing number), identifier (i.e., account number), identifierType (e.g., tokenized account number), or type (e.g., US_ACH, US_RTP)
  • Returns a single account
  • Supports all applicable account categories

Customer Info (/customers/v2/{providerId}/current) Updated

• Added support for the CustomerToAccountRelationship FDX entity which includes:
  • accounts array of:
    • accountId Id of end-user’s account
    • relationship relationship between the listed account and the current customer, for example: PRIMARY, SECONDARY_JOINT, or POWER_OF_ATTORNEY
• No changes to the existing data elements
• The versioning has been updated to /v2
• Responses include
  • Customer info related data elements such as name, email, addresses, telephones, or relationships (i.e., account holder relationship to an account)
  • Returns end-user information which is not account category specific

Statement List (/statements/{version}/{providerId}/{accountId}) New

• Allows retrieval of statements for your end-user's consented accounts (up to two years of historical statements, depend on provider)
• Typical use: retrieve a list of statements for the consented account
• Responses include
  • An array of statements, where each includes accountId, statementId, description, and status.
  • links to GET individual statements in PDF, GIF, JPG, TIFF, or PNG format

Statement (/statements/{version}/{providerId}/{accountId}/{statementId}) New

• Allows the retrieval of an individual statement in PDF, GIF, JPG, TIFF, or PNG format by passing in the statementId path parameter obtained in the Statement List response. The file format is specified by including a value for Accept in the header. Accepted values are:
  • application/pdf
  • image/gif
  • image/jpg
  • image/tiff
  • image/png
• Typical use: retrieve a statement image for the consented account
• Responses include:
  • an image of the account statement identified by statementId