Logo

API EXPLORER

OBP APIs (all tags) (130)

The full set of Open Bank Project APIs supports functionality including transaction history, payments, onboarding & KYC, cards, customer and customer messages, counterparty and transaction metadata, delegated account access, data redaction and entitlements.

Bank

Accounts

Views

Counterparties

Transactions

Create counterparty for an account

Create counterparty.

Counterparties are created for the account / view They are how the user of the view (e.g. account owner) refers to the other side of the transaction

name is the human readable name (e.g. Piano teacher, Miss Nipa)

other_bank_id is an (internal) ID for the bank of the bank of the counterparty (if known)

other_account_id is an (internal) ID for the bank account of the counterparty (if known)

other_account_provider is a code that tells the system where that bank is hosted. Will be OBP if its known to the API. Usage of this flag (in API / connectors) is work in progress.

account_routing_scheme is a code that dictates the nature of the account_routing_address e.g. IBAN

account_routing_address is an instance of account_routing_scheme that can be used to route payments to external systems. e.g. an IBAN number

bank_routing_scheme is a code that dictates the nature of the bank_routing_address e.g. "BIC",

bank_routing_address is an instance of bank_routing_scheme

is_beneficiary must be set to true in order to send payments to this counterparty

The view specified by VIEW_ID must have the canAddCounterparty permission

Authentication is Mandatory

Implmented in 2_1_0 by createCounterparty

Enable or Disable Consumers

Enable/Disable a Consumer specified by CONSUMER_ID.

Implmented in 2_1_0 by enableDisableConsumers

Get Consumer

Get the Consumer specified by CONSUMER_ID.

Implmented in 2_1_0 by getConsumer

Get Consumers

Get the all Consumers.

Implmented in 2_1_0 by getConsumers

Get Metrics

Get the all metrics

require CanReadMetrics role

Implmented in 2_1_0 by getMetrics

Search API Metrics via Elasticsearch.

Search the API calls made to this API instance via Elastic Search.

Login is required.

CanSearchMetrics entitlement is required to search metrics data.

parameters:

esType - elasticsearch type

simple query:

q - plain_text_query

df - default field to search

sort - field to sort on

size - number of hits returned, default 10

from - show hits starting from

json query:

source - JSON_query_(URL-escaped)

example usage:

/search/metrics/q=findThis

or:

/search/metrics/source={"query":{"query_string":{"query":"findThis"}}}

Note!!

The whole JSON query string MUST be URL-encoded:

  • For { use %7B
  • For } use %7D
  • For : use %3A
  • For " use %22

etc..

Only q, source and esType are passed to Elastic

Elastic simple query: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-uri-request.html

Elastic JSON query: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-filter-context.html

Implmented in 2_0_0 by elasticSearchMetrics

Search Warehouse Data Via Elasticsearch

Search warehouse data via Elastic Search.

Login is required.

CanSearchWarehouse entitlement is required to search warehouse data!

Send your email, name, project name and user_id to the admins to get access.

Elastic (search) is used in the background. See links below for syntax.

parameters:

esType - elasticsearch type

simple query:

q - plain_text_query

df - default field to search

sort - field to sort on

size - number of hits returned, default 10

from - show hits starting from

json query:

source - JSON_query_(URL-escaped)

Example usage:

GET /search/warehouse/q=findThis

or:

GET /search/warehouse/source={"query":{"query_string":{"query":"findThis"}}}

Note!!

The whole JSON query string MUST be URL-encoded:

  • For { use %7B
  • For } use %7D
  • For : use %3A
  • For " use %22

etc..

Only q, source and esType are passed to Elastic

Elastic simple query: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-uri-request.html

Elastic JSON query: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-filter-context.html

You can specify the esType thus: /search/warehouse/esType=type&q=a

Implmented in 2_0_0 by elasticSearchWarehouse

Update Consumer RedirectUrl

Update an existing redirectUrl for a Consumer specified by CONSUMER_ID.

CONSUMER_ID can be obtained after you register the application.

Or use the endpoint 'Get Consumers' to get it

Implmented in 2_1_0 by updateConsumerRedirectUrl

The root of the API

Returns information about:

  • API version
  • Hosted by information
  • Git Commit
Implmented in 1_2_1 by root

Add cards for a bank

Import bulk data into the sandbox (Authenticated access).

This is can be used to create cards which are stored in the local RDBMS. Authentication is Mandatory

Implmented in 2_1_0 by addCardsForBank

Create Account

Create Account at bank specified by BANK_ID with Id specified by NEW_ACCOUNT_ID.

The User can create an Account for themself or an Account for another User if they have CanCreateAccount role.

If USER_ID is not specified the account will be owned by the logged in User.

Note: The Amount must be zero.

Implmented in 2_0_0 by createAccount

Create Branch

Create branch for the bank (Authenticated access). Authentication is Mandatory

Implmented in 2_1_0 by createBranch

Create View.

Create a view on bank account

OAuth authentication is required and the user needs to have access to the owner view. The 'alias' field in the JSON can take one of three values:

  • public: to use the public alias if there is one specified for the other account.
  • private: to use the public alias if there is one specified for the other account.
  • ''(empty string): to use no alias; the view shows the real name of the other account.

The 'hide_metadata_if_alias_used' field in the JSON can take boolean values. If it is set to true and there is an alias on the other account then the other accounts' metadata (like more_info, url, image_url, open_corporates_url, etc.) will be hidden. Otherwise the metadata will be shown.

The 'allowed_actions' field is a list containing the name of the actions allowed on this view, all the actions contained will be set to true on the view creation, the rest will be set to false.

Implmented in 1_2_1 by createViewForBankAccount

Create sandbox

Import bulk data into the sandbox (Authenticated access).

This call can be used to create banks, users, accounts and transactions which are stored in the local RDBMS.

The user needs to have CanCreateSandbox entitlement.

An example of an import set of data (json) can be found here Authentication is Mandatory

Implmented in 2_1_0 by sandboxDataImport

Delete View

Deletes the view specified by VIEW_ID on the bank account specified by ACCOUNT_ID at bank BANK_ID.

Implmented in 1_2_1 by deleteViewForBankAccount

Get Account by Id (Core)

Information returned about the account specified by ACCOUNT_ID:

  • Number
  • Owners
  • Type
  • Balance
  • IBAN

This call returns the owner view and requires access to that view.

OAuth authentication is required

Implmented in 2_0_0 by getCoreAccountById

Get Account by Id (Full)

Information returned about an account specified by ACCOUNT_ID as moderated by the view (VIEW_ID):

  • Number
  • Owners
  • Type
  • Balance
  • IBAN
  • Available views (sorted by short_name)

More details about the data moderation by the view here.

PSD2 Context: PSD2 requires customers to have access to their account information via third party applications. This call provides balance and other account information via delegated authenticaiton using OAuth.

OAuth authentication is required if the 'is_public' field in view (VIEW_ID) is not set to true.

Implmented in 2_0_0 by accountById

Get Accounts at Bank (Public)

Returns a list of the public accounts (Anonymous access) at BANK_ID. For each account the API returns the ID and the available views.

Authentication via OAuth is not required.

Implmented in 2_0_0 by publicAccountsAtOneBank

Get Accounts at all Banks (Private)

Get private accounts at all banks (Authenticated access) Returns the list of accounts containing private views for the user at all banks. For each account the API returns the ID and the available views.

Authentication is Mandatory

Implmented in 2_0_0 by corePrivateAccountsAllBanks

Get Accounts at one Bank (Public and Private).

Get accounts at one bank that the user has access to (Authenticated + Anonymous access). Returns the list of accounts at BANK_ID that the user has access to. For each account the API returns the account ID and the available views.

If the user is not authenticated, the list will contain only the accounts providing public views. Authentication is Optional

Implmented in 2_0_0 by allAccountsAtOneBank

Get Counterparty by Id.

Returns data about a counterparty (aka Other Account) that had shared at least one transaction with ACCOUNT_ID at BANK_ID. Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by getCounterpartyByIdForBankAccount

Get Public Accounts at all Banks.

Get public accounts at all banks (Anonymous access). Returns accounts that contain at least one public view (a view where is_public is true) For each account the API returns the ID and the available views.

Authentication is Optional

Implmented in 2_0_0 by publicAccountsAllBanks

Get Transaction by Id.

Returns one transaction specified by TRANSACTION_ID of the account ACCOUNT_ID and moderated by the view (VIEW_ID).

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by getTransactionByIdForBankAccount

Get Transactions for Account (Core)

Returns transactions list (Core info) of the account specified by ACCOUNT_ID.

Authentication is required.

Possible custom headers for pagination:

  • obp_sort_by=CRITERIA ==> default value: "completed" field
  • obp_sort_direction=ASC/DESC ==> default value: DESC
  • obp_limit=NUMBER ==> default value: 50
  • obp_offset=NUMBER ==> default value: 0
  • obp_from_date=DATE => default value: date of the oldest transaction registered (format below)
  • obp_to_date=DATE => default value: date of the newest transaction registered (format below)

Date format parameter: "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" (2014-07-01T00:00:00.000Z) ==> time zone is UTC.

Implmented in 2_0_0 by getCoreTransactionsForBankAccount

Get Transactions for Account (Full)

Returns transactions list of the account specified by ACCOUNT_ID and moderated by the view (VIEW_ID).

Authentication via OAuth is required if the view is not public.

Possible custom headers for pagination:

  • obp_sort_by=CRITERIA ==> default value: "completed" field
  • obp_sort_direction=ASC/DESC ==> default value: DESC
  • obp_limit=NUMBER ==> default value: 50
  • obp_offset=NUMBER ==> default value: 0
  • obp_from_date=DATE => default value: date of the oldest transaction registered (format below)
  • obp_to_date=DATE => default value: date of the newest transaction registered (format below)

Date format parameter: "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" (2014-07-01T00:00:00.000Z) ==> time zone is UTC.

Implmented in 1_2_1 by getTransactionsForBankAccount

Get Views for Account.

Views

Views in Open Bank Project provide a mechanism for fine grained access control and delegation to Accounts and Transactions. Account holders use the 'owner' view by default. Delegated access is made through other views for example 'accountants', 'share-holders' or 'tagging-application'. Views can be created via the API and each view has a list of entitlements.

Views on accounts and transactions filter the underlying data to redact certain fields for certain users. For instance the balance on an account may be hidden from the public. The way to know what is possible on a view is determined in the following JSON.

Data: When a view moderates a set of data, some fields my contain the value null rather than the original value. This indicates either that the user is not allowed to see the original data or the field is empty.

There is currently one exception to this rule; the 'holder' field in the JSON contains always a value which is either an alias or the real name - indicated by the 'is_alias' field.

Action: When a user performs an action like trying to post a comment (with POST API call), if he is not allowed, the body response will contain an error message.

Metadata: Transaction metadata (like images, tags, comments, etc.) will appears ONLY on the view where they have been created e.g. comments posted to the public view only appear on the public view.

The other account metadata fields (like image_URL, more_info, etc.) are unique through all the views. Example, if a user edits the 'more_info' field in the 'team' view, then the view 'authorities' will show the new value (if it is allowed to do it).

All

Optional

Returns the list of the views created for account ACCOUNT_ID at BANK_ID.

OAuth authentication is required and the user needs to have access to the owner view.

Implmented in 1_2_1 by getViewsForBankAccount

Get all Accounts at all Banks.

Get all accounts at all banks the User has access to (Authenticated + Anonymous access). Returns the list of accounts at that the user has access to at all banks. For each account the API returns the account ID and the available views.

If the user is not authenticated via OAuth, the list will contain only the accounts providing public views. If the user is authenticated, the list will contain non-public accounts to which the user has access, in addition to all public accounts.

Authentication is Optional

Implmented in 2_0_0 by allAccountsAllBanks

Get private accounts at one bank (Authenticated access).

Returns the list of private (non-public) accounts at BANK_ID that the user has access to. For each account the API returns the ID and the available views.

If you want to see more information on the Views, use the Account Detail call. If you want less information about the account, use the /my accounts call

Authentication is Mandatory

Implmented in 2_0_0 by privateAccountsAtOneBank

Update Account Label.

Update the label for the account. The label is how the account is known to the account owner e.g. 'My savings account'

Implmented in 1_2_1 by updateAccountLabel

Update Branch

Update an existing branch for a bank account (Authenticated access). Authentication is Mandatory

Implmented in 2_1_0 by updateBranch

Update View.

Update an existing view on a bank account

OAuth authentication is required and the user needs to have access to the owner view.

The json sent is the same as during view creation (above), with one difference: the 'name' field of a view is not editable (it is only set when a view is created)

Implmented in 1_2_1 by updateViewForBankAccount

Create Transaction Type offered by the bank

Create Transaction Types for the bank specified by BANK_ID:

  • id : Unique transaction type id across the API instance. SHOULD be a UUID. MUST be unique.
  • bank_id : The bank that supports this TransactionType
  • short_code : A short code (SHOULD have no-spaces) which MUST be unique across the bank. May be stored with Transactions to link here
  • summary : A succinct summary
  • description : A longer description
  • charge : The charge to the customer for each one of these

Authentication is Mandatory

Implmented in 2_1_0 by createTransactionType

Get Bank

Get the bank specified by BANK_ID Returns information about a single bank specified by BANK_ID including:

  • Short and full name of bank
  • Logo URL
  • Website
Implmented in 1_2_1 by bankById

Get Bank ATM

Returns information about ATM for a single bank specified by BANK_ID and ATM_ID including:

  • Address
  • Geo Location
  • License the data under this endpoint is released under

Authentication is Optional

Implmented in 2_1_0 by getAtm

Get Bank ATMS

Returns information about ATMs for a single bank specified by BANK_ID including:

  • Address
  • Geo Location
  • License the data under this endpoint is released under

Authentication is Optional

Implmented in 1_4_0 by getAtms

Get Bank Branch

Returns information about branches for a single bank specified by BANK_ID and BRANCH_ID including:

  • Name
  • Address
  • Geo Location
  • License the data under this endpoint is released under

Authentication is Optional

Implmented in 2_1_0 by getBranch

Get Bank Branches

Returns information about branches for a single bank specified by BANK_ID including:

  • Name
  • Address
  • Geo Location
  • License the data under this endpoint is released under

Authentication is Optional

Implmented in 1_4_0 by getBranches

Get Bank Product

Returns information about the financial products offered by a bank specified by BANK_ID and PRODUCT_CODE including:

  • Name
  • Code
  • Category
  • Family
  • Super Family
  • More info URL
  • Description
  • Terms and Conditions
  • License the data under this endpoint is released under Authentication is Optional
Implmented in 2_1_0 by getProduct

Get Bank Products

Returns information about the financial products offered by a bank specified by BANK_ID including:

  • Name
  • Code
  • Category
  • Family
  • Super Family
  • More info URL
  • Description
  • Terms and Conditions
  • License the data under this endpoint is released under Authentication is Optional
Implmented in 2_1_0 by getProducts

Get Banks

Get banks on this API instance Returns a list of banks supported on this server:

  • ID used as parameter in URLs
  • Short and full name of bank
  • Logo URL
  • Website
Implmented in 1_2_1 by getBanks

Get Transaction Types offered by the bank

Get Transaction Types for the bank specified by BANK_ID:

Lists the possible Transaction Types available at the bank (as opposed to Transaction Request Types which are the possible ways Transactions can be created by this API Server).

  • id : Unique transaction type id across the API instance. SHOULD be a UUID. MUST be unique.
  • bank_id : The bank that supports this TransactionType
  • short_code : A short code (SHOULD have no-spaces) which MUST be unique across the bank. May be stored with Transactions to link here
  • summary : A succinct summary
  • description : A longer description
  • charge : The charge to the customer for each one of these

Authentication is Optional

Implmented in 2_0_0 by getTransactionTypes

Get the Transaction Request Types supported by the bank

Get the list of the Transaction Request Types supported by the bank.

Authentication is Optional

Implmented in 2_1_0 by getTransactionRequestTypesSupportedByBank

Add KYC Check

Add a KYC check for the customer specified by CUSTOMER_ID. KYC Checks store details of checks on a customer made by the KYC team, their comments and a satisfied status.

Implmented in 2_0_0 by addKycCheck

Add KYC Document.

Add a KYC document for the customer specified by CUSTOMER_ID. KYC Documents contain the document type (e.g. passport), place of issue, expiry etc.

Implmented in 2_0_0 by addKycDocument

Add KYC Media.

Add some KYC media for the customer specified by CUSTOMER_ID. KYC Media resources relate to KYC Documents and KYC Checks and contain media urls for scans of passports, utility bills etc.

Implmented in 2_0_0 by addKycMedia

Add KYC Status

Add a kyc_status for the customer specified by CUSTOMER_ID. KYC Status is a timeline of the KYC status of the customer

Implmented in 2_0_0 by addKycStatus

Add Social Media Handle

Add a social media handle for the customer specified by CUSTOMER_ID.

Implmented in 2_0_0 by addSocialMediaHandle
Implmented in 1_4_0 by getCrmEvents

Get KYC Checks for current Customer

Get KYC checks for the logged in customer Messages sent to the currently authenticated user.

Authentication is Mandatory

Implmented in 2_0_0 by getKycChecks

Get KYC Documents for Customer

Get KYC (know your customer) documents for a customer Get a list of documents that affirm the identity of the customer Passport, driving licence etc. Authentication is Optional

Implmented in 2_0_0 by getKycDocuments

Get KYC Media for a customer

Get KYC media (scans, pictures, videos) that affirms the identity of the customer.

Authentication is Mandatory

Implmented in 2_0_0 by getKycMedia

Get cards for the current user

Returns data about all the physical cards a user has been issued. These could be debit cards, credit cards, etc.

Implmented in 1_3_0 by getCards
Implmented in 1_3_0 by getCardsForBank

Get customer for logged in user

Information about the currently authenticated user.

Authentication via OAuth is required.

Implmented in 2_1_0 by getCustomer

Get social media handles for a customer

Get social media handles for a customer.

Authentication is Mandatory

Implmented in 2_0_0 by getSocialMediaHandles

Get the KYC statuses for a customer

Get the KYC statuses for a customer over time

Authentication is Mandatory

Implmented in 2_0_0 by getKycStatuses

Create Meeting (video conference/call)

Create Meeting: Initiate a video conference/call with the bank.

The Meetings resource contains meta data about video/other conference sessions, not the video/audio/chat itself.

The actual conferencing is handled by external providers. Currently OBP supports tokbox video conferences (WIP).

This is not a recomendation of tokbox per se.

provider_id determines the provider of the meeting / video chat service. MUST be url friendly (no spaces).

purpose_id explains the purpose of the chat. onboarding | mortgage | complaint etc. MUST be url friendly (no spaces).

Login is required.

This call is experimental. Currently staff_user_id is not set. Further calls will be needed to correctly set this.

Implmented in 2_0_0 by createMeeting

Get Meeting

Get Meeting specified by BANK_ID / MEETING_ID Meetings contain meta data about, and are used to facilitate, video conferences / chats etc.

The actual conference/chats are handled by external services.

Login is required.

This call is experimental and will require further authorisation in the future.

Implmented in 2_0_0 by getMeeting

Get Meetings

Meetings contain meta data about, and are used to facilitate, video conferences / chats etc.

The actual conference/chats are handled by external services.

Login is required.

This call is experimental and will require further authorisation in the future.

Implmented in 2_0_0 by getMeetings

Add Corporate Location to Counterparty

Add the geolocation of the counterparty's registered address

Implmented in 1_2_1 by addCounterpartyCorporateLocation

Add Counterparty More Info

Add a description of the counter party from the perpestive of the account e.g. My dentist.

Implmented in 1_2_1 by addCounterpartyMoreInfo

Add Open Corporates URL to Counterparty

Add open corporates url to other bank account.

Implmented in 1_2_1 by addCounterpartyOpenCorporatesUrl

Add a tag.

Posts a tag about a transaction TRANSACTION_ID on a view VIEW_ID.

Authentication is Mandatory

Authentication is required as the tag is linked with the user.

Implmented in 1_2_1 by addTagForViewOnTransaction

Add an image.

Posts an image about a transaction TRANSACTION_ID on a view VIEW_ID.

Authentication is Mandatory

The image is linked with the user.

Implmented in 1_2_1 by addImageForViewOnTransaction

Add comment.

Posts a comment about a transaction TRANSACTION_ID on a view VIEW_ID.

${authenticationRequiredMessage(false)}

Authentication is required since the comment is linked with the user.

Implmented in 1_2_1 by addCommentForViewOnTransaction

Add image url to other bank account.

Add a url that points to the logo of the counterparty

Implmented in 1_2_1 by addCounterpartyImageUrl

Add narrative.

Creates a description of the transaction TRANSACTION_ID.

Note: Unlike other items of metadata, there is only one "narrative" per transaction accross all views. If you set narrative via a view e.g. view-x it will be seen via view-y (as long as view-y has permission to see the narrative).

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by addTransactionNarrative

Add physical location to other bank account.

Add geocoordinates of the counterparty's main location

Implmented in 1_2_1 by addCounterpartyPhysicalLocation

Add public alias to other bank account.

Creates the public alias for the other account OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Note: Public aliases are automatically generated for new 'other accounts / counterparties', so this call should only be used if the public alias was deleted.

The VIEW_ID parameter should be a view the caller is permitted to access to and that has permission to create public aliases.

Implmented in 1_2_1 by addCounterpartyPublicAlias

Add url to other bank account.

A url which represents the counterparty (home page url etc.)

Implmented in 1_2_1 by addCounterpartyUrl

Add where tag.

Creates a "where" Geo tag on a transaction TRANSACTION_ID in a view.

Authentication is Mandatory

The geo tag is linked with the user.

Implmented in 1_2_1 by addWhereTagForViewOnTransaction

Create Counterparty Private Alias

Creates a private alias for the other account OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by addCounterpartyPrivateAlias

Delete Counterparty Corporate Location.

Delete corporate location of other bank account. Delete the geolocation of the counterparty's registered address

Implmented in 1_2_1 by deleteCounterpartyCorporateLocation

Delete Counterparty Image URL

Delete image url of other bank account.

Implmented in 1_2_1 by deleteCounterpartyImageUrl

Delete Counterparty Open Corporates URL

Delete open corporate url of other bank account.

Implmented in 1_2_1 by deleteCounterpartyOpenCorporatesUrl

Delete Counterparty Physical Location.

Delete physical location of other bank account.

Implmented in 1_2_1 by deleteCounterpartyPhysicalLocation

Delete Counterparty Private Alias

Deletes the private alias of the other account OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by deleteCounterpartyPrivateAlias

Delete Counterparty Public Alias

Deletes the public alias of the other account OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by deleteCounterpartyPublicAlias

Delete a tag.

Deletes the tag TAG_ID about the transaction TRANSACTION_ID made on view.

Authentication via OAuth is required. The user must either have owner privileges for this account, or must be the user that posted the tag.

Implmented in 1_2_1 by deleteTagForViewOnTransaction

Delete an image

Deletes the image IMAGE_ID about the transaction TRANSACTION_ID made on view.

Authentication via OAuth is required. The user must either have owner privileges for this account, or must be the user that posted the image.

Implmented in 1_2_1 by deleteImageForViewOnTransaction

Delete comment.

Delete the comment COMMENT_ID about the transaction TRANSACTION_ID made on view.

Authentication via OAuth is required. The user must either have owner privileges for this account, or must be the user that posted the comment.

Implmented in 1_2_1 by deleteCommentForViewOnTransaction
Implmented in 1_2_1 by deleteCounterpartyMoreInfo

Delete narrative.

Deletes the description of the transaction TRANSACTION_ID.

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by deleteTransactionNarrative
Implmented in 1_2_1 by deleteCounterpartyUrl

Delete where tag.

Deletes the where tag of the transaction TRANSACTION_ID made on view.

Authentication is Mandatory

The user must either have owner privileges for this account, or must be the user that posted the geo tag.

Implmented in 1_2_1 by deleteWhereTagForViewOnTransaction

Get Counterparty Metadata.

Get metadata of one counterparty (other account). Returns only the metadata about one other bank account (OTHER_ACCOUNT_ID) that had shared at least one transaction with ACCOUNT_ID at BANK_ID.

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getCounterpartyMetadata

Get Counterparty Private Alias

Returns the private alias of the other account OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by getCounterpartyPrivateAlias

Get comments.

Returns the transaction TRANSACTION_ID comments made on a view (VIEW_ID).

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getCommentsForViewOnTransaction

Get images.

Returns the transaction TRANSACTION_ID images made on a view (VIEW_ID).

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getImagesForViewOnTransaction

Get narrative.

Returns the account owner description of the transaction moderated by the view.

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getTransactionNarrative

Get public alias of other bank account.

Returns the public alias of the other account OTHER_ACCOUNT_ID. Authentication is Optional OAuth authentication is required if the view is not public.

Implmented in 1_2_1 by getCounterpartyPublicAlias

Get tags.

Returns the transaction TRANSACTION_ID tags made on a view (VIEW_ID).

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getTagsForViewOnTransaction

Get where tag.

Returns the "where" Geo tag added to the transaction TRANSACTION_ID made on a view (VIEW_ID). It represents the location where the transaction has been initiated.

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getWhereTagForViewOnTransaction

Update Counterparty Corporate Location

Update the geolocation of the counterparty's registered address

Implmented in 1_2_1 by updateCounterpartyCorporateLocation

Update Counterparty Image Url

Update the url that points to the logo of the counterparty

Implmented in 1_2_1 by updateCounterpartyImageUrl

Update Counterparty More Info

Update the more info description of the counter party from the perpestive of the account e.g. My dentist.

Implmented in 1_2_1 by updateCounterpartyMoreInfo

Update Counterparty Physical Location

Update geocoordinates of the counterparty's main location

Implmented in 1_2_1 by updateCounterpartyPhysicalLocation

Update Counterparty Private Alias

Updates the private alias of the counterparty (AKA other account) OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by updateCounterpartyPrivateAlias

Update Open Corporates Url of Counterparty

Update open corporate url of other bank account.

Implmented in 1_2_1 by updateCounterpartyOpenCorporatesUrl

Update narrative.

Updates the description of the transaction TRANSACTION_ID.

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by updateTransactionNarrative

Update public alias of other bank account.

Updates the public alias of the other account / counterparty OTHER_ACCOUNT_ID.

Authentication is Optional Authentication is required if the view is not public.

Implmented in 1_2_1 by updateCounterpartyPublicAlias

Update url of other bank account.

A url which represents the counterparty (home page url etc.)

Implmented in 1_2_1 by updateCounterpartyUrl

Update where tag.

Updates the "where" Geo tag on a transaction TRANSACTION_ID in a view.

Authentication is Mandatory

The geo tag is linked with the user.

Implmented in 1_2_1 by updateWhereTagForViewOnTransaction

Create User.

Creates OBP user. No authorisation (currently) required.

Mimics current webform to Register.

Requires username(email) and password.

Returns 409 error if username not unique.

May require validation of email address.

Implmented in 2_0_0 by createUser

Add Customer Message.

Add a message for the customer specified by CUSTOMER_ID

Implmented in 1_4_0 by addCustomerMessage

Create Customer.

Add a customer linked to the user specified by user_id The Customer resource stores the customer number, legal name, email, phone number, their date of birth, relationship status, education attained, a url for a profile image, KYC status etc. This call may require additional permissions/role in the future. For now the authenticated user can create at most one linked customer. Dates need to be in the format 2013-01-21T23:08:00Z Authentication is Mandatory

Implmented in 2_1_0 by createCustomer

Link a customer and a user This call may require additional permissions/role in the future. For now the authenticated user can create at most one linked customer at any one bank. Authentication is Mandatory

Implmented in 2_0_0 by createUserCustomerLinks

Get Counterparties of one Account.

Returns data about all the counterparties (other accounts) that have shared at least one transaction with the ACCOUNT_ID at BANK_ID. Authentication is Optional Authentication is required if the view VIEW_ID is not public.

Implmented in 1_2_1 by getCounterpartiesForBankAccount

Get Customer Messages (current)

Get messages for the logged in customer Messages sent to the currently authenticated user.

Authentication via OAuth is required.

Implmented in 1_4_0 by getCustomerMessages

Get User (Current)

Get the logged in user

Login is required.

Implmented in 2_0_0 by getCurrentUser

Get Users by Email Address

Get users by email address

Login is required. CanGetAnyUser entitlement is required,

Implmented in 2_0_0 by getUser

Get access for specific user.

Returns the list of the views at BANK_ID for account ACCOUNT_ID that a USER_ID at their provider PROVIDER_ID has access to. All url parameters must be %-encoded, which is often especially relevant for USER_ID and PROVIDER_ID.

OAuth authentication is required and the user needs to have access to the owner view.

Implmented in 2_0_0 by getPermissionForUserForBankAccount

Get access.

Returns the list of the permissions at BANK_ID for account ACCOUNT_ID, with each time a pair composed of the user and the views that he has access to.

OAuth authentication is required and the user needs to have access to the owner view.

Implmented in 2_0_0 by getPermissionsForBankAccount

Get all Users

Get all users

Login is required. CanGetAnyUser entitlement is required,

Implmented in 2_1_0 by getUsers

Get all customers for logged in user

Information about the currently authenticated user.

Authentication via OAuth is required.

Implmented in 2_1_0 by getCustomers

Grant User access to View.

Grants the user USER_ID at their provider PROVIDER_ID access to the view VIEW_ID at BANK_ID for account ACCOUNT_ID. All url parameters must be %-encoded, which is often especially relevant for USER_ID and PROVIDER_ID.

OAuth authentication is required and the user needs to have access to the owner view.

Granting access to a public view will return an error message, as the user already has access.

Implmented in 1_2_1 by addPermissionForUserForBankAccountForOneView

Grant User access to a list of views.

Grants the user USER_ID at their provider PROVIDER_ID access to a list of views at BANK_ID for account ACCOUNT_ID.

All url parameters must be %-encoded, which is often especially relevant for USER_ID and PROVIDER_ID.

OAuth authentication is required and the user needs to have access to the owner view.

Implmented in 1_2_1 by addPermissionForUserForBankAccountForMultipleViews

Revoke access to all Views on Account

Revokes the user USER_ID at their provider PROVIDER_ID access to all the views at BANK_ID for account ACCOUNT_ID.

OAuth authentication is required and the user needs to have access to the owner view.

Implmented in 1_2_1 by removePermissionForUserForBankAccountForAllViews

Revoke access to one View.

Revokes the user USER_ID at their provider PROVIDER_ID access to the view VIEW_ID at BANK_ID for account ACCOUNT_ID.

Revoking a user access to a public view will return an error message.

OAuth authentication is required and the user needs to have access to the owner view.

Implmented in 1_2_1 by removePermissionForUserForBankAccountForOneView

Get Counterparty of Transaction

Get other account of a transaction. Returns details of the other party involved in the transaction, moderated by the view (VIEW_ID).

Authentication via OAuth is required if the view is not public.

Implmented in 1_2_1 by getCounterpartyForTransaction

Answer Transaction Request Challenge.

In Sandbox mode, any string that can be converted to a positive integer will be accepted as an answer.

Implmented in 2_1_0 by answerTransactionRequestChallenge

Create Transaction Request.

Initiate a Payment via a Transaction Request.

This is the preferred method to create a payment and supersedes makePayment in 1.2.1.

In OBP, a transaction request may or may not result in a transaction. A transaction only has one possible state: completed.

A transaction request on the other hand can have one of several states.

Think of transactions as items in a bank statement that represent the movement of money.

Think of transaction requests as orders to move money which may or may not succeeed and result in a transaction.

A transaction request might create a security challenge that needs to be answered before the transaction request proceeds.

Transaction Requests contain charge information giving the client the opportunity to proceed or not (as long as the challenge level is appropriate).

Transaction Requests can have one of several Transaction Request Types which expect different bodies. The escaped body is returned in the details key of the GET response. This provides some commonality and one URL for many different payment or transfer types with enough flexibility to validate them differently.

The payer is set in the URL. Money comes out of the BANK_ID and ACCOUNT_ID specified in the URL.

The payee is set in the request body. Money goes into the BANK_ID and ACCOUNT_ID specified in the request body.

In sandbox mode, TRANSACTION_REQUEST_TYPE is commonly set to SANDBOX_TAN. See getTransactionRequestTypesSupportedByBank for all supported types.

In sandbox mode, if the amount is less than 1000 EUR (any currency, unless it is set differently on this server), the transaction request will create a transaction without a challenge, else the Transaction Request will be set to INITIALISED and a challenge will need to be answered.

If a challenge is created you must answer it using Answer Transaction Request Challenge before the Transaction is created.

You can transfer between different currency accounts. (new in 2.0.0). The currency in body must match the sending account.

The following static FX rates are available in sandbox mode:

{ "XAF":{ "KRW":1.87975, "GBP":0.00131092, "AED":0.00601555, "INR":0.110241, "JPY":0.185328, "USD":0.00163773, "EUR":0.00152449 }, "KRW":{ "XAF":0.531986, "GBP":6.97389E-4, "AED":0.00320019, "INR":0.0586469, "JPY":0.0985917, "USD":8.7125E-4, "EUR":8.11008E-4 }, "GBP":{ "XAF":762.826, "KRW":1433.92, "AED":4.58882, "INR":84.095, "JPY":141.373, "USD":1.2493, "EUR":1.16278 }, "AED":{ "XAF":166.236, "KRW":312.482, "GBP":0.217921, "INR":18.3255, "JPY":30.8081, "USD":0.27225, "EUR":0.253425 }, "INR":{ "XAF":9.07101, "KRW":17.0512, "GBP":0.0118913, "AED":0.0545671, "JPY":1.68111, "USD":0.0148559, "EUR":0.0138287 }, "JPY":{ "XAF":5.39585, "KRW":10.1428, "GBP":0.0070735, "AED":0.032459, "INR":0.594846, "USD":0.00883695, "EUR":0.00822592 }, "USD":{ "XAF":610.601, "KRW":1147.78, "GBP":0.800446, "AED":3.6731, "INR":67.3135, "JPY":113.161, "EUR":0.930886 }, "EUR":{ "XAF":655.957, "KRW":1233.03, "GBP":0.860011, "AED":3.94594, "INR":72.3136, "JPY":121.567, "USD":1.07428 } }

PSD2 Context: Third party access access to payments is a core tenent of PSD2.

This call satisfies that requirement from several perspectives:

1) A transaction can be initiated by a third party application.

2) The customer is informed of the charge that will incurred.

3) The call uses delegated authentication (OAuth)

See this python code for a complete example of this flow.

Authentication is Mandatory

Implmented in 2_1_0 by createTransactionRequest

Get Transaction Request Types for Account

Returns the Transation Request Types that the account specified by ACCOUNT_ID and view specified by VIEW_ID has access to.

These are the ways this API Server can create a Transaction via a Transaction Request (as opposed to Transaction Types which include external types too e.g. for Transactions created by core banking etc.)

A Transaction Request Type internally determines:

  • the required Transaction Request 'body' i.e. fields that define the 'what' and 'to' of a Transaction Request,
  • the type of security challenge that may be be raised before the Transaction Request proceeds, and
  • the threshold of that challenge.

For instance in a 'SANDBOX_TAN' Transaction Request, for amounts over 1000 currency units, the user must supply a positive integer to complete the Transaction Request and create a Transaction.

This approach aims to provide only one endpoint for initiating transactions, and one that handles challenges, whilst still allowing flexibility with the payload and internal logic.

Implmented in 1_4_0 by getTransactionRequestTypes

Get Transaction Requests.

Returns transaction requests for account specified by ACCOUNT_ID at bank specified by BANK_ID.

The VIEW_ID specified must be 'owner' and the user must have access to this view.

Version 2.0.0 now returns charge information.

Transaction Requests serve to initiate transactions that may or may not proceed. They contain information including:

  • Transaction Request Id
  • Type
  • Status (INITIATED, COMPLETED)
  • Challenge (in order to confirm the request)
  • From Bank / Account
  • Details including Currency, Value, Description and other initiation information specific to each type. (Could potentialy include a list of future transactions.)
  • Related Transactions

PSD2 Context: PSD2 requires transparency of charges to the customer. This endpoint provides the charge that would be applied if the Transaction Request proceeds - and a record of that charge there after. The customer can proceed with the Transaction by answering the security challenge.

Implmented in 2_1_0 by getTransactionRequests

Add Entitlement for a User.

Create Entitlement. Grant Role to User.

Entitlements are used to grant System or Bank level roles to Users. (For Account level privileges, see Views)

For a System level Role (.e.g CanGetAnyUser), set bank_id to an empty string i.e. "bank_id":""

For a Bank level Role (e.g. CanCreateAccount), set bank_id to a valid value e.g. "bank_id":"my-bank-id"

Authentication is required and the user needs to be a Super Admin. Super Admins are listed in the Props file.

Implmented in 2_0_0 by addEntitlement

Delete Entitlement

Delete Entitlement specified by ENTITLEMENT_ID for an user specified by USER_ID

Authentication is required and the user needs to be a Super Admin. Super Admins are listed in the Props file.

Implmented in 2_0_0 by deleteEntitlement
Implmented in 2_1_0 by getEntitlementsByBankAndUser
Implmented in 2_0_0 by getEntitlements

Get Roles

Returns all available roles

Login is required.

Implmented in 2_1_0 by getRoles

Get all Entitlements

Login is required.

Implmented in 2_0_0 by getAllEntitlements