Postman collection

Learn more about Postman with their Getting started guide.

For page updates, check the change log.



We recommend using Postman for testing. Access our Postman workspace here: Akoya API v1 | Akoya API | Postman API Network.


🚧

Registering with Akoya

In order to use this collection, you must first receive a client id and client secret from Akoya.


Visit our Postman workspace, with included Sandbox parameters. Parameters are defined below.


Run in PostmanRun in Postman


Working with Akoya's Postman collection

Our API collection is titled “Akoya API v<#>” where “#” is the version number of the current release. As of this writing, the latest release is version 1:

Postman API CollectionPostman API Collection

Postman API Collection


Edit access to the collection is restricted. You can either:

  • Export the collection to JSON

  • Create a fork in your own personal workspace


Environment

Once you’ve imported/forked your own local copy of the collection, click “Environments” to modify variable values per your needs:

Postman EnvironmentPostman Environment

Postman Environment

Environment parameters

Below are the environment parameters:

ParameterDescription
accountIdThe id of the consumer’s permissioned account
access_urlURL for Data Access API endpoints
sandbox: sandbox-access.ddp.akoya.com
production: access.ddp.akoya.com
client_idYour application’s client id from Akoya. Client id/secret combinations are issued for each app in each environment. More details on the client credentials specification: https://tools.ietf.org/html/rfc6749#section-3.2.1
sandbox: your sandbox app id
prod: a production client id/secret combo will be provided for each recipient app
client_secretYour app’s client secret
connectorThe Akoya identifier for the data provider your user will be logging in to. Akoya takes this identifier and directs the user through the appropriate provider's login flow.
sandbox: mikomo
prod: provider ids are available after onboarding
id_tokenThe id token is used as a bearer token with all data requests. It is a short-lived token which must be refreshed on a periodic basis.
idp_urlThe URL for the identity provider service used in the authentication and authorization flow.
sandbox: (Mikomo) sandbox-idp.ddp.akoya.com
production: idp.ddp.akoya.com
permission_urlURL for the “Revoke Token” endpoint
sandbox: sandbox-permission.api.ddp.akoya.com
production: permission.api.ddp.akoya.com
products_urlThe URL for Akoya products.
sandbox: sandbox-products.ddp.akoya.com
providerIdThe id of the data provider of the account permissioned by the consumer
sandbox: mikomo
redirect_uriThe redirect URI must be registered with Akoya for the appropriate client id. Akoya will validate that the redirect URI exactly matches the one registered to prevent malicious redirects. The redirect URI specifies where the end-user is sent after authentication. More details on redirection: https://tools.ietf.org/html/rfc6749#section-3.1.2
refresh_tokenA refresh token is used to obtain a new ID token without requiring the end-user to provide credentials or reauthenticate every time the ID token expires. The refresh token is longer-lived and is only used for maintaining the id token, not as a token for requesting data.

Definitions

More information on other parameters used in the collection

ParameterEndpoint(s)Method(s)Description
codetokenGETAuthorization code received in the redirect after authorization. More details on specification: https://tools.ietf.org/html/rfc6749#section-1.3.1
grant_typetoken, refresh_tokenPOSTDepends on the request (i.e. access token request, refresh token request, client credentials request)

token: authorization_code

refresh: refresh_token

An authorization grant is a credential representing the resource owner's authorization used by the client to obtain an access token. More details on authorization: https://tools.ietf.org/html/rfc6749#section-1.3

Tips & tricks

  1. You may also test against Postman mock servers by following the instructions provided here.
  2. To view the documentation of the endpoint, click on the documentation icon on the right:
Postman documentation iconPostman documentation icon

Postman documentation icon


To see all documentation in a new tab, select “View complete collection documentation” at the bottom of the documentation tab:

Postman - View documentation linkPostman - View documentation link

Postman - View documentation link


Testing our endpoints with Postman

These instructions are compatible with Postman v8.2.1+


📌 After installing the Akoya for data recipients collection, please ensure the parameters in your environment file are correct.


Akoya provides secure (TLS v1.2) access to RESTful APIs that are based on the API/Data Structures as defined by the Financial Data Exchange. All data requests use standard GET and POST methods and must include a bearer token in the authorization header. All responses are returned in JSON format.


End-user authentication


End-users must authenticate with their data providers before you can get their data.

  1. Your application sends users to their provider’s login page via the Akoya platform.

  2. After successfully authentication, the provider presents users with an authorization page requesting permission to share their data with your app.

  3. If permission is granted, your application is issued two tokens (id and refresh) from Akoya which give you permissioned access to end-user data.

  4. If end users do not grant permission to share data, Akoya will send them back to your application (to the page of your choosing).


📘 For your convenience, Akoya has made available Mikomo Bank, a mock financial institution, with test users and data. To see the collection of users, visit
Mikomo Bank.


See the “Getting Started” page in the API docs for instructions on setting up a DR Hub account and getting ready to test our APIs.

See the Mikomo test users document for information on available test accounts. In our sandbox environment, the providerId will always be mikomo.

Below is a brief overview of our endpoints. More thorough documentation is available at our API docs page.

Accounts

📌

Note

The output below is sample output for instructional purposes, and is not specific to any of the data providers
on our network.


The Accounts endpoint returns a JSON object with a set of account details for one or more accounts at a provider. The path parameter providerId is required. You can return either full account details, or a "lightweight" version:

Example "lightweight" account response objectExample "lightweight" account response object

Example "lightweight" account response object

Example "detailed account response objectExample "detailed account response object

Example "detailed account response object

Postman screen - Accounts endpointPostman screen - Accounts endpoint

Postman screen - Accounts endpoint


Transactions

The Transactions endpoint returns a JSON object containing transaction histories of consumer-permissioned accounts; thus, when testing this endpoint, you must ensure the Mikomo test account you choose has permissioned transactions associated with it.

This endpoint requires accountId and providerId. You can also specify start and end times, a max number of transactions to return, and an offset:

Example Transactions endpoint response objectExample Transactions endpoint response object

Example Transactions endpoint response object

Postman Screen - Transactions endpointPostman Screen - Transactions endpoint

Postman Screen - Transactions endpoint


Payment networks

The Payment networks endpoint returns JSON data necessary for facilitating use cases such as payment enablement or account opening. accountId (mikomo_9 in the sandbox environment) and providerId are required for the payments endpoint:


Example Payment networks endpoint response objectExample Payment networks endpoint response object

Example Payment networks endpoint response object

Postman Screen - Payment networks endpointPostman Screen - Payment networks endpoint

Postman Screen - Payment networks endpoint


Customers

The Customers endpoint returns a JSON response with customer data, supporting use cases such as payment enablement, account opening, or lending/credit enhancements. providerId is required for the Customers endpoint:


Example Customers endpoint response objectExample Customers endpoint response object

Example Customers endpoint response object

Postman Screen - Customers endpointPostman Screen - Customers endpoint

Postman Screen - Customers endpoint


Change log

DateUpdate
2022‑Feb‑16Added products_url variable to support new Akoya Payments and Customers products. For more on these products, see: Release Notes.
2022‑Mar‑16Merged "Getting Started" page into this document; Updated to reflect Akoya API v1; added clarifications