API Explorer

v3.1.0 (249 APIs)

Bank
Accounts
Views
Counterparties
Transactions

Create Counterparty (Explicit)

Create Counterparty (Explicit) for an Account.

In OBP, there are two types of Counterparty.

  • Explicit Counterparties (those here) which we create explicitly and are used in COUNTERPARTY Transaction Requests

  • Implicit Counterparties (AKA Other Accounts) which are generated automatically from the other sides of Transactions.

Explicit 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 : the human readable name (e.g. Piano teacher, Miss Nipa)

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

bank_routing_scheme : eg: bankId or bankCode or any other strings

bank_routing_address : eg: gh.29.uk, must be valid sandbox bankIds

account_routing_scheme : eg: AccountId or AccountNumber or any other strings

account_routing_address : eg: 1d65db7c-a7b2-4839-af41-95, must be valid accountIds

other_account_secondary_routing_scheme : eg: IBan or any other strings

other_account_secondary_routing_address : if it is an IBAN, it should be unique for each counterparty.

other_branch_routing_scheme : eg: branchId or any other strings or you can leave it empty, not useful in sandbox mode.

other_branch_routing_address : eg: branch-id-123 or you can leave it empty, not useful in sandbox mode.

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

bespoke: It supports a list of key-value, you can add it to the counterparty.

bespoke.key : any info-key you want to add to this counterparty

bespoke.value : any info-value you want to add to this counterparty

The view specified by VIEW_ID must have the canAddCounterparty permission

A minimal example for TransactionRequestType == COUNTERPARTY
{
"name": "Tesobe1",
"description": "Good Company",
"other_bank_routing_scheme": "OBP",
"other_bank_routing_address": "gh.29.uk",
"other_account_routing_scheme": "OBP",
"other_account_routing_address": "8ca8a7e4-6d02-48e3-a029-0b2bf89de9f0",
"is_beneficiary": true,
"other_account_secondary_routing_scheme": "",
"other_account_secondary_routing_address": "",
"other_branch_routing_scheme": "",
"other_branch_routing_address": "",
"bespoke": []
}

A minimal example for TransactionRequestType == SEPA

{
"name": "Tesobe2",
"description": "Good Company",
"other_bank_routing_scheme": "OBP",
"other_bank_routing_address": "gh.29.uk",
"other_account_routing_scheme": "OBP",
"other_account_routing_address": "8ca8a7e4-6d02-48e3-a029-0b2bf89de9f0",
"other_account_secondary_routing_scheme": "IBAN",
"other_account_secondary_routing_address": "DE89 3704 0044 0532 0130 00",
"is_beneficiary": true,
"other_branch_routing_scheme": "",
"other_branch_routing_address": "",
"bespoke": []
}

Authentication is Mandatory

URL Parameters:

JSON request body fields:

JSON response body fields:

Typical Successful Response:

								
									
{ "name":"CounterpartyName", "description":"My landlord", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "this_bank_id":"gh.29.uk", "this_account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "this_view_id":"owner", "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh", "other_bank_routing_scheme":"OBP", "other_bank_routing_address":"gh.29.uk", "other_branch_routing_scheme":"OBP", "other_branch_routing_address":"12f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_routing_scheme":"OBP", "other_account_routing_address":"36f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }], "metadata":{ "public_alias":"String", "more_info":"String", "url":"String", "image_url":"String", "open_corporates_url":"String", "corporate_location":{ "latitude":11.45, "longitude":11.45, "date":"2017-09-19T00:00:00Z", "user":{ "id":"123", "provider":"http://127.0.0.1:8080", "username":"felixsmith" } }, "physical_location":{ "latitude":11.45, "longitude":11.45, "date":"2017-09-19T00:00:00Z", "user":{ "id":"123", "provider":"http://127.0.0.1:8080", "username":"felixsmith" } }, "private_alias":"String" } }
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30110: Invalid Account Id. The ACCOUNT_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.
  • OBP-30111: Invalid Bank Id. The BANK_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-30003: Account not found. Please specify a valid value for ACCOUNT_ID.
  • OBP-10001: Incorrect json format.
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30014: Counterparty already exists. Please specify a different value for BANK_ID or ACCOUNT_ID or VIEW_ID or NAME.
  • OBP-50000: Unknown Error.
Implemented in OBPv2.2.0 by createCounterparty, operation_id: OBPv2.2.0-createCounterparty

Get Counterparties (Explicit)

Get the Counterparties (Explicit) for the account / view.

Authentication is Mandatory

URL Parameters:

JSON response body fields:

Typical Successful Response:

								
									
{ "counterparties":[{ "name":"CounterpartyName", "description":"My landlord", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "this_bank_id":"gh.29.uk", "this_account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "this_view_id":"owner", "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh", "other_bank_routing_scheme":"OBP", "other_bank_routing_address":"gh.29.uk", "other_branch_routing_scheme":"OBP", "other_branch_routing_address":"12f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_routing_scheme":"OBP", "other_account_routing_address":"36f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }] }] }
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30022: The current view does not have the permission:
  • OBP-20017: Current user does not have access to the view. Please specify a valid value for VIEW_ID.
  • OBP-50000: Unknown Error.
Implemented in OBPv2.2.0 by getExplictCounterpartiesForAccount, operation_id: OBPv2.2.0-getExplictCounterpartiesForAccount

Get Counterparty by Counterparty Id (Explicit)

Information returned about the Counterparty specified by COUNTERPARTY_ID:

Authentication is Mandatory

URL Parameters:

JSON response body fields:

Typical Successful Response:

								
									
{ "name":"CounterpartyName", "description":"My landlord", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "this_bank_id":"gh.29.uk", "this_account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "this_view_id":"owner", "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh", "other_bank_routing_scheme":"OBP", "other_bank_routing_address":"gh.29.uk", "other_branch_routing_scheme":"OBP", "other_branch_routing_address":"12f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_routing_scheme":"OBP", "other_account_routing_address":"36f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }], "metadata":{ "public_alias":"String", "more_info":"String", "url":"String", "image_url":"String", "open_corporates_url":"String", "corporate_location":{ "latitude":11.45, "longitude":11.45, "date":"2017-09-19T00:00:00Z", "user":{ "id":"123", "provider":"http://127.0.0.1:8080", "username":"felixsmith" } }, "physical_location":{ "latitude":11.45, "longitude":11.45, "date":"2017-09-19T00:00:00Z", "user":{ "id":"123", "provider":"http://127.0.0.1:8080", "username":"felixsmith" } }, "private_alias":"String" } }
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-50000: Unknown Error.
Implemented in OBPv2.2.0 by getExplictCounterpartyById, operation_id: OBPv2.2.0-getExplictCounterpartyById

Get Other Account by Id

Returns data about the Other Account that has shared at least one transaction with ACCOUNT_ID at BANK_ID.
Authentication is Optional

Authentication is required if the view is not public.

URL Parameters:

JSON response body fields:

Typical Successful Response:

								
									
{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "holder":{ "name":"OBP", "is_alias":true }, "bank_routing":{ "scheme":"Bank_ID", "address":"gh.29.uk" }, "account_routings":[{ "scheme":"AccountNumber", "address":"4930396" }], "metadata":{ "public_alias":"NONE", "private_alias":"NONE", "more_info":"www.openbankproject.com", "URL":"www.openbankproject.com", "image_URL":"www.openbankproject.com", "open_corporates_URL":"www.openbankproject.com", "corporate_location":{ "latitude":1.231, "longitude":1.231, "date":"2017-09-19T00:00:00Z", "user":{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "provider":"http://127.0.0.1:8080", "display_name":"OBP" } }, "physical_location":{ "latitude":1.231, "longitude":1.231, "date":"2017-09-19T00:00:00Z", "user":{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "provider":"http://127.0.0.1:8080", "display_name":"OBP" } } } }
Possible Errors:
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Implemented in OBPv3.0.0 by getOtherAccountByIdForBankAccount, operation_id: OBPv3.0.0-getOtherAccountByIdForBankAccount

Get Other Accounts of one Account

Returns data about all the 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.

URL Parameters:

JSON response body fields:

Typical Successful Response:

								
									
{ "other_accounts":[{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "holder":{ "name":"OBP", "is_alias":true }, "bank_routing":{ "scheme":"Bank_ID", "address":"gh.29.uk" }, "account_routings":[{ "scheme":"AccountNumber", "address":"4930396" }], "metadata":{ "public_alias":"NONE", "private_alias":"NONE", "more_info":"www.openbankproject.com", "URL":"www.openbankproject.com", "image_URL":"www.openbankproject.com", "open_corporates_URL":"www.openbankproject.com", "corporate_location":{ "latitude":1.231, "longitude":1.231, "date":"2017-09-19T00:00:00Z", "user":{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "provider":"http://127.0.0.1:8080", "display_name":"OBP" } }, "physical_location":{ "latitude":1.231, "longitude":1.231, "date":"2017-09-19T00:00:00Z", "user":{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "provider":"http://127.0.0.1:8080", "display_name":"OBP" } } } }] }
Possible Errors:
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Implemented in OBPv3.0.0 by getOtherAccountsForBankAccount, operation_id: OBPv3.0.0-getOtherAccountsForBankAccount