Institutions v0.2.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Operations related to bank and credit union financial institutions (FIs). There are two features in this API:
- Calculating upcoming dates for transfer schedules, factoring in weekends, non-business days, and banking holidays as determined by the institution.
- Look up a financial institution by an FI locator value: either an ABA routing and transit number, an IBAN account number, or a SWIFT/BIC code.
Download OpenAPI Definition (YAML)
Base URLs:
License: Apiture API License
Authentication
- API Key (
apiKey
)- header parameter: API-Key
- API Key based client identification. See details at Secure Access.
- OpenID Connect authentication (
accessToken
)- OpenId Connect (OIDC) authentication/authorization. The client uses the
authorization_endpoint
andtoken_endpoint
to obtain an access token to pass in theAuthorization
header. Those endpoints are available via the OIDC Configuration URL. The actual URL may vary with each financial institution. See details at Secure Access. - OIDC Configuration URL =
https://oidc.apiture.com/oidc/.well-known/oidc-configuration
- OpenId Connect (OIDC) authentication/authorization. The client uses the
Institutions
Banking Institutions
lookUpInstitutionByLocator
Code samples
# You can also use wget
curl -X GET https://api.apiture.com/banking/institutionByLocator?locator=string&locatorType=abaRoutingNumber&countryCode=US \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET https://api.apiture.com/banking/institutionByLocator?locator=string&locatorType=abaRoutingNumber&countryCode=US HTTP/1.1
Host: api.apiture.com
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.apiture.com/banking/institutionByLocator?locator=string&locatorType=abaRoutingNumber&countryCode=US',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
var headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.apiture.com/banking/institutionByLocator',
method: 'get',
data: '?locator=string&locatorType=abaRoutingNumber&countryCode=US',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.apiture.com/banking/institutionByLocator',
params: {
'locator' => 'string',
'locatorType' => '[institutionLocatorType](#schemainstitutionlocatortype)',
'countryCode' => 'string'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.apiture.com/banking/institutionByLocator', params={
'locator': 'string', 'locatorType': 'abaRoutingNumber', 'countryCode': 'US'
}, headers = headers)
print r.json()
URL obj = new URL("https://api.apiture.com/banking/institutionByLocator?locator=string&locatorType=abaRoutingNumber&countryCode=US");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.apiture.com/banking/institutionByLocator", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Look up institution by routing number, IBAN, or SWIFT/BIC code
GET https://api.apiture.com/banking/institutionByLocator
Look up a financial institution by their country code and either American Bankers Association routing number, by International Bank Account Number (IBAN), or by SWIFT Business Business Identifier Code (BIC) code. Optionally, include a list of intermediary institutions that may be necessary to complete international wire transfers.
Parameters
Parameter | Description |
---|---|
locator | string (required) The financial institution lookup key (routing number, IBAN, or SWIFT/BIC), as indicated by the locatorType query parameter.maxLength: 36 |
locatorType | institutionLocatorType (required) Indicates what type of value the locator query parameter is.enum values: abaRoutingNumber , swiftBicCode , ibanAccountNumber |
countryCode | string (required) The country code in which to search for institutions. For the US, the locatorType must be abaRoutingNumber . For non-US countries, the locatorType must be swiftBicCode or ibanAccountNumber .minLength: 2 maxLength: 2 |
includeIntermediaryInstitutions | boolean If looking up a beneficiary institution for a wire transfer beneficiary institution, request the response also include a list of intermediary institutions. |
Example responses
200 Response
{
"found": true,
"institution": {
"name": "First Bank of Andalasia",
"address": {
"address1": "239 West Princess Ave.",
"locality": "Andalasia",
"regionCode": "NC",
"countryCode": "US",
"postalCode": "28407"
},
"locator": "503000196",
"locatorType": "abaRoutingNumber"
}
}
Responses
Status | Description |
---|---|
200 | OK |
OK. | |
Schema: institutionLookupResult |
Status | Description |
---|---|
400 | Bad Request |
Bad Request. The request body, request headers, and/or query parameters are not well-formed. | |
Schema: problemResponse |
Status | Description |
---|---|
401 | Unauthorized |
Unauthorized. The operation require authentication but none was given. This error response may have one of the following
| |
Schema: problemResponse | |
Header | WWW-Authenticate string |
Optionally indicates the authentication scheme(s) and parameters applicable to the target resource/operation. This normally occurs if the request requires authentication but no authentication was passed. A 401 Unauthorized response may also be used for operations that have valid credentials but which require step-up authentication. |
Status | Description |
---|---|
403 | Forbidden |
Forbidden. The authenticated caller is not authorized to perform the requested operation. This error response may have one of the following
| |
Schema: problemResponse |
Status | Description |
---|---|
422 | Unprocessable Entity |
Unprocessable Entity. The request body and/or query parameters were well formed but otherwise invalid. This error response may have one of the following
| |
Schema: problemResponse |
Schedules
Schedules
listTransferSchedule
Code samples
# You can also use wget
curl -X GET https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule?startsOn=2022-07-04&direction=debit&frequency=once \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule?startsOn=2022-07-04&direction=debit&frequency=once HTTP/1.1
Host: api.apiture.com
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule?startsOn=2022-07-04&direction=debit&frequency=once',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
var headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
$.ajax({
url: 'https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule',
method: 'get',
data: '?startsOn=2022-07-04&direction=debit&frequency=once',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule',
params: {
'startsOn' => 'string(date)',
'direction' => '[transferScheduleDirection](#schematransferscheduledirection)',
'frequency' => '[transferFrequency](#schematransferfrequency)'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule', params={
'startsOn': '2022-07-04', 'direction': 'debit', 'frequency': 'once'
}, headers = headers)
print r.json()
URL obj = new URL("https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule?startsOn=2022-07-04&direction=debit&frequency=once");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
Return this institution's list of upcoming transfer schedule dates
GET https://api.apiture.com/banking/institutions/{institutionId}/transferSchedule
Return a transfer schedule list for this institution.
Parameters
Parameter | Description |
---|---|
institutionId | string (required) The unique identifier of a financial institution. This is an opaque string. |
startsOn | string(date) (required) The date to use to begin calculations of the transfer schedule in YYYY-MM-DD RFC 3339 date format. |
endsOn | string(date) The date to use to conclude calculations of the transfer schedule in YYYY-MM-DD RFC 3339 date format. |
direction | transferScheduleDirection (required) The direction of the transfer from the institution to the customer used for adjusting transfer dates due to banking holidays. For debit , dates are adjusted to the next business day. For credit , dates are adjusted to the previous business day.enum values: debit , credit |
count | integer(int32) The maximum amount of dates to calculate and include in the response. If an end date is provided, the total count may be lower than the requested count. Default: 6 minimum: 1 maximum: 12 |
frequency | transferFrequency (required) The interval at which the money movement recurs. enum values: once , daily , weekly , biweekly , semimonthly , monthly , monthlyFirstDay , monthlyLastDay , bimonthly , quarterly , semiyearly , yearly |
Example responses
200 Response
{
"items": [
{
"scheduledOn": "2022-06-27",
"effectiveOn": "2022-06-27"
},
{
"scheduledOn": "2022-07-04",
"effectiveOn": "2022-07-05"
},
{
"scheduledOn": "2022-07-11",
"effectiveOn": "2022-07-11"
},
{
"scheduledOn": "2022-07-18",
"effectiveOn": "2022-07-18"
},
{
"scheduledOn": "2022-07-25",
"effectiveOn": "2022-07-25"
},
{
"scheduledOn": "2022-08-01",
"effectiveOn": "2022-07-01"
}
]
}
Responses
Status | Description |
---|---|
200 | OK |
OK. | |
Schema: transferSchedules |
Status | Description |
---|---|
400 | Bad Request |
Bad Request. The request body, request headers, and/or query parameters are not well-formed. | |
Schema: problemResponse |
Status | Description |
---|---|
401 | Unauthorized |
Unauthorized. The operation require authentication but none was given. This error response may have one of the following
| |
Schema: problemResponse | |
Header | WWW-Authenticate string |
Optionally indicates the authentication scheme(s) and parameters applicable to the target resource/operation. This normally occurs if the request requires authentication but no authentication was passed. A 401 Unauthorized response may also be used for operations that have valid credentials but which require step-up authentication. |
Status | Description |
---|---|
403 | Forbidden |
Forbidden. The authenticated caller is not authorized to perform the requested operation. This error response may have one of the following
| |
Schema: problemResponse |
Status | Description |
---|---|
422 | Unprocessable Entity |
Unprocessable Entity. The request body and/or query parameters were well formed but otherwise invalid. | |
Schema: problemResponse |
Schemas
address
{
"address1": "1805 Tiburon Dr.",
"address2": "Building 14, Suite 1500",
"locality": "Wilmington",
"regionName": "North Carolina",
"countryCode": "US",
"postalCode": "28412"
}
Address (v1.1.0)
A postal address that can hold a US address or an international (non-US) postal addresses.
Properties
Name | Description |
---|---|
address1 | string (required) The first line of the postal address. In the US, this typically includes the building number and street name. maxLength: 35 |
address2 | string The second line of the street address. This should only be used if it has a value. Typical values include building numbers, suite numbers, and other identifying information beyond the first line of the postal address. maxLength: 35 |
locality | string (required) The city/town/municipality of the address. maxLength: 20 |
countryCode | string (required) The ISO-3611 alpha-2 value for the country associated with the postal address. minLength: 2 maxLength: 2 |
regionName | string The state, district, or outlying area of the postal address. This is required if countryCode is not US . regionCode and regionName are mutually exclusive.minLength: 2 maxLength: 20 |
regionCode | string The state, district, or outlying area of the postal address. This is required if countryCode is US regionCode and regionName are mutually exclusive.minLength: 2 maxLength: 2 |
postalCode | string (required) The postal code, which varies in format by country. If countryCode is US , this should be a five digit US ZIP code or ten character ZIP+4.minLength: 5 maxLength: 10 |
apiProblem
{
"id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
"type": "https://production.api.apiture.com/errors/accountNotFound/v1.0.0",
"title": "Account Not Found",
"status": 422,
"occurredAt": "2022-04-25T12:42:21.375Z",
"detail": "No account exists at the given account_url",
"instance": "https://production.api.apiture.com/banking/transfers/bb709151-575041fcd617"
}
API Problem (v1.1.0)
API problem or error, as per RFC 7807 application/problem+json.
Properties
Name | Description |
---|---|
type | string(uri-reference) A URI reference (RFC3986) that identifies the problem type. If present, this is the URL of human-readable HTML documentation for the problem type. When this member is not present, its value is assumed to be "about:blank" . |
title | string A short, human-readable summary of the problem type. The title is usually the same for all problem with the same type . |
status | integer(int32) The HTTP status code for this occurrence of the problem. minimum: 100 maximum: 599 |
detail | string A human-readable explanation specific to this occurrence of the problem. |
instance | string(uri-reference) A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment |
id | string: readOnlyResourceId The unique identifier for this problem. This is an immutable opaque string. read-only minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
occurredAt | string(date-time): readOnlyTimestamp The timestamp when the problem occurred, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC.read-only minLength: 20 maxLength: 30 |
problems | array: [apiProblem] Optional root-causes if there are multiple problems in the request or API call processing. |
attributes | object Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. |
institutionLocatorType
"abaRoutingNumber"
institution Locator Type (v1.0.0)
Indicates the type of the institution locator
.
institutionLocatorType
strings may have one of the following enumerated values:
Value | Description |
---|---|
abaRoutingNumber | ABA Routing Number: The American Bankers Association routing number of a financial institution |
swiftBicCode | swiftBicCode: The SWIFT Business Business Identifier Code (BIC) code of a financial institution |
ibanAccountNumber | IBAN: |
Type: string
enum values: abaRoutingNumber
, swiftBicCode
, ibanAccountNumber
institutionLookupResult
{
"found": true,
"institution": {
"name": "First Bank of Andalasia",
"address": {
"address1": "239 West Princess Ave.",
"locality": "Andalasia",
"regionCode": "NC",
"countryCode": "US",
"postalCode": "28407"
},
"locator": "503000196",
"locatorType": "abaRoutingNumber"
}
}
Institution Lookup Result (v1.0.0)
Successful institution lookup result.
Properties
Name | Description |
---|---|
found | boolean (required) true if a financial institution was found matching the requested FI locator, false if none was found. |
institution | object: simpleInstitution The name and other informatin about the financial institution, if found. |
intermediaryInstitutions | array: [simpleInstitution] Optional intermediary institutions, if requested and if intermediary institutions are required for for international wire transfers to the beneficiary institution. This array is omitted if there none are required. minLength: 1 maxLength: 8 |
problemResponse
{
"id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
"type": "https://production.api.apiture.com/errors/noSuchAccount/v1.0.0",
"title": "Account Not Found",
"status": 422,
"occurredAt": "2022-04-25T12:42:21.375Z",
"detail": "No account exists for the given account reference",
"instance": "https://production.api.apiture.com/banking/transfers/bb709151-575041fcd617"
}
Problem Response (v0.3.0)
API problem or error response, as per RFC 7807 application/problem+json.
Properties
Name | Description |
---|---|
type | string(uri-reference) A URI reference (RFC3986) that identifies the problem type. If present, this is the URL of human-readable HTML documentation for the problem type. When this member is not present, its value is assumed to be "about:blank" . |
title | string A short, human-readable summary of the problem type. The title is usually the same for all problem with the same type . |
status | integer(int32) The HTTP status code for this occurrence of the problem. minimum: 100 maximum: 599 |
detail | string A human-readable explanation specific to this occurrence of the problem. |
instance | string(uri-reference) A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment |
id | string: readOnlyResourceId The unique identifier for this problem. This is an immutable opaque string. read-only minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
occurredAt | string(date-time): readOnlyTimestamp The timestamp when the problem occurred, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC.read-only minLength: 20 maxLength: 30 |
problems | array: [apiProblem] Optional root-causes if there are multiple problems in the request or API call processing. |
attributes | object Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. |
readOnlyResourceId
"string"
Read-only Resource Identifier (v1.0.0)
The unique, opaque system-assigned identifier for a resource. This case-sensitive ID is also used in URLs as path parameters or in other properties or parameters that reference a resource by ID rather than URL. Resource IDs are immutable.
Type: string
read-only
minLength: 6
maxLength: 48
pattern: ^[-_:.~$a-zA-Z0-9]+$
readOnlyTimestamp
"2021-10-30T19:06:04.250Z"
Read-Only Timestamp (v1.0.0)
A readonly or derived timestamp (an instant in time) formatted in RFC 3339 date-time
UTC format: YYYY-MM-DDThh:mm:ss.sssZ
.
The schema readOnlyTimestamp
was added on version 0.4.0
of the API.
Type: string(date-time)
read-only
minLength: 20
maxLength: 30
resourceId
"string"
Resource Identifier (v1.0.0)
The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.
Type: string
minLength: 6
maxLength: 48
pattern: ^[-_:.~$a-zA-Z0-9]+$
simpleInstitution
{
"name": "First Bank of Andalasia",
"address": {
"address1": "239 West Princess Ave.",
"locality": "Andalasia",
"regionCode": "NC",
"countryCode": "US",
"postalCode": "28407"
},
"locator": "503000196",
"locatorType": "abaRoutingNumber"
}
Simple Institution (v1.0.0)
A simple representation of a financial institution.
Properties
Name | Description |
---|---|
name | string (required) The financial institution's name. maxLength: 35 |
address | object: address (required) The financial institution's postal mailing address. |
locator | string (required) The American Bankers Association routing number, SWIFT Business Business Identifier Code (BIC) code, or IBAN account number of the institution. The form of this institution locator string is set with the locatorType property.maxLength: 36 |
locatorType | string: institutionLocatorType (required) Indicates the type of this institution's locator .enum values: abaRoutingNumber , swiftBicCode , ibanAccountNumber |
transferFrequency
"once"
Transfer Frequency (v1.0.0)
For recurring transfers, the interval at which the money movement recurs.
transferFrequency
strings may have one of the following enumerated values:
Value | Description |
---|---|
once | once: Transfer does not repeat |
daily | daily: Repeat daily on business days |
weekly | weekly: Repeat weekly |
biweekly | biweekly: Repeat every two weeks (26 times a year) |
semimonthly | semimonthly: Repeat twice a month (24 times a year) |
monthly | monthly: Repeat monthly |
monthlyFirstDay | monthlyFirstDay: Repeat on the first business day of the month |
monthlyLastDay | monthlyLastDay: Repeat on the last business day of the month |
bimonthly | bimonthly: Repeat every other month |
quarterly | quarterly: Repeat quarterly (four times a year) |
semiyearly | semiyearly: Repeat every six months (twice a year) |
yearly | yearly: Repeat once every year |
Type: string
enum values: once
, daily
, weekly
, biweekly
, semimonthly
, monthly
, monthlyFirstDay
, monthlyLastDay
, bimonthly
, quarterly
, semiyearly
, yearly
transferScheduleDirection
"debit"
Transfer Schedule Direction (v1.0.0)
Provides the direction in which a transfer flows.
transferScheduleDirection
strings may have one of the following enumerated values:
Value | Description |
---|---|
debit | Debit: Money flow for a payment from a customer to a financial institution |
credit | Payment Direction: Money flow for a payment from a financial institution to a customer |
Type: string
enum values: debit
, credit
transferScheduleItem
{
"scheduledOn": "2022-07-04",
"effectiveOn": "2022-07-05"
}
Transfer Schedule Item (v1.0.0)
Summary representation of a transfer schedule resource in transfer schedule list.
Properties
Name | Description |
---|---|
scheduledOn | string(date) (required) The scheduled date of the calculated calendar recurrence in YYYY-MM-DD RFC 3339 date format. |
effectiveOn | string(date) (required) The effective date of the recurrence in YYYY-MM-DD RFC 3339 date format. When the effective date differs from the scheduled date, it is due to a banking holiday, weekend, or other non-business day. The date is adjusted to before the scheduled date when the transfer direction is credit and adjusted to after the scheduled date when the transfer direction is debit . |
transferSchedules
{
"items": [
{
"scheduledOn": "2022-06-27",
"effectiveOn": "2022-06-27"
},
{
"scheduledOn": "2022-07-04",
"effectiveOn": "2022-07-05"
},
{
"scheduledOn": "2022-07-11",
"effectiveOn": "2022-07-11"
},
{
"scheduledOn": "2022-07-18",
"effectiveOn": "2022-07-18"
},
{
"scheduledOn": "2022-07-25",
"effectiveOn": "2022-07-25"
},
{
"scheduledOn": "2022-08-01",
"effectiveOn": "2022-07-01"
}
]
}
Transfer Schedule List (v1.0.0)
List of transfer methods. The items in the list are ordered in the items
array.
Properties
Name | Description |
---|---|
items | array: [transferScheduleItem] (required) An array containing upcoming transfer schedule items. |