Postman collection
We recommend using Postman for testing. Please visit the Postman Akoya workspace for our collections and environment (default values for use in Sandbox). Parameters are defined below.
Registering with Akoya
In order to use Akoya's Postman collections, you must first receive a client id and secret from Akoya.
Installing and configuring the Postman app
The Postman app is available for the Mac, Windows, and Linux operating systems. For more information, please see Installing and updating Postman.
You may need to change some app defaults depending on your personal preferences or company network environment. Please refer to Setting up Postman for a detailed explanation of Postman settings.
Working with Akoya's Postman collection
Edit access to the collection is restricted. You may:
- Export the collection to JSON
- Create a fork in your own personal workspace
Postman API collection
Environment
Once you’ve imported/forked your own local copy of the collection, fork a local copy of the Environments from the collection. You can find some of the variable values for your account on the My apps page of the Data Recipient Hub. Click the “Environments” tab to update the variables to your specific values.
Postman environment
Environment parameters
| Parameter | Description |
|---|---|
accountId | The id of the consumer’s permissioned account |
client_id | Your 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_secret | Your app’s client secret |
connector | The Akoya identifier for the data provider your user will be logging in to. Usually the same as providerId (below). 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_token | The 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_url | The 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 |
links_prev | Stored value for paging transactions to previous page. |
links_next | Stored value for paging transactions to next page. |
permission_url | URL for the “Revoke token” endpoint sandbox: sandbox-permission.api.ddp.akoya.com production: permission.api.ddp.akoya.com |
products_url | The URL for Akoya products. sandbox: sandbox-products.ddp.akoya.com |
providerId | The id of the data provider of the account permissioned by the consumer sandbox: mikomo |
redirect_uri | The 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_token | A 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. |
version | The version of the Akoya product APIs |
statementId | The long-term persistent identity of the statement |
Definitions
More information on other parameters used in the collection
| Parameter | Endpoint(s) | Method(s) | Description |
|---|---|---|---|
code | token | GET | Authorization code received in the redirect after authorization. More details on specification: <<https://tools.ietf.org/html/rfc6749#section-1.3.1>> |
grant_type | token, refresh_token | POST | Depends 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
- You may also test against Postman mock servers by following the instructions provided here.
- To view the documentation of the endpoint, click on the documentation icon on the right.
Postman documentation icon
- By default, the Postman app uses your operating system's configured proxy to send API requests or access the internet. If needed, you can enter authentication details for the default proxy in the Postman app. You can also configure Postman to use the system proxy or a custom proxy when sending requests. See Postman's "Getting Started" guide for more info.
Testing our endpoints with Postman
These instructions are compatible with Postman v8.2.1+
After installing the Akoya 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.
-
Your application sends users to their provider’s login page via the Akoya platform.
-
After successful authentication, the provider presents users with an authorization page requesting permission to share their data with your app.
-
If permission is granted, your application is issued two tokens (id and refresh) from Akoya which give you permissioned access to end-user data.
-
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 users.
See the “Getting Started” page in the API docs for instructions on setting up a 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 in our API docs.
Products
Note
The output below is sample output for instructional purposes, and is not specific to any of the data providers on our network.
Akoya product endpoints return JSON objects with a set of account details for one or more accounts at a provider. The path parameter providerId is required. The results will vary by product.
Account information
The Account information 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:
Postman screen - Account information endpoint
Example “lightweight” account response object
Example “detailed” account response object
Transactions
The Transactions endpoint returns a JSON object containing transaction histories of consumer-permissioned accounts. 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:
Postman screen - Transactions endpoint
Example Transactions endpoint response object
Payments
The Payments endpoint returns JSON data necessary for facilitating use cases such as payment enablement or account opening. accountId and providerId are required for the payments endpoint.
Postman screen - Payment 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.
Postman screen - Customers endpoint
Example Customers endpoint response object
Statement list
The Statement list endpoint returns a JSON response containing a list of available statements for the end user's consented accounts. The results also include links to GET the statement image via the Statement endpoint.
Postman screen - Statement list endpoint
Statement
The Statement endpoint returns a specific account statement file in PDF format using a statementId obtained from a call to Statement list.
Postman screen - Statement endpoint
Troubleshooting in Postman
If you're having trouble using the Postman app, it may be due to network firewalls, proxy server settings, or other issues you may be able to debug through the Postman Console. Use the Postman Troubleshooting page for tips on debugging and troubleshooting.
Change log
| Date | Update |
|---|---|
| 2024-Aug-06 | Added dev help resources. |
| 2024-May-29 | Updated images to reflect v2 endpoints; added subsections for Statement and Statement list. |
| 2022-Oct-04 | Added two new sections: "Installing and configuring the Postman app" and "Troubleshooting Postman." |
| 2022-Aug-18 | Updated collections and examples for Akoya API v2 release. |
| 2022‑Mar‑16 | Merged "Getting Started" page into this document; Updated to reflect Akoya API v1; added clarifications. |
| 2022‑Feb‑16 | Added products_url variable to support new Akoya Payments and Customers products. For more on these products, see: Release Notes. |
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 about 2 months ago