Create Instrument

Create or Add an external instrument to Qolo platform. The external instrument may be a bank account or a credit/debit card or any other account held by another financial institution.

To add bank account use the following conditions
If instrument_type = BANKDDA then provide an account_number and routing_number
If instrument_type = IBAN then provide IBAN in account_number field and swiftBicCode in bank_identifier field
If instrument_type = BBAN then provide account_number , swiftBicCode in bank_identifier field (if applicable)
and additional rounting info in routing_number field

Qolo also blocks transfers to certain countries and you will not be able to add the bank accounts / cards from the blocked countries.

Request
Security:
Bearer
path Parameters
version
required
string
Request Body schema: application/json
outside_instrument_guid
string <uuid>

Unique ID of the external instrument on Qolo Platform. An external instrument is defined as an external bank account or card.

person_guid
required
string <uuid>

Unique Person ID on Qolo Platform.

instrument_country
required
string non-empty

Country of the instrument. Country 3-ISO code such as USA.

instrument_type
required
string (InstrumentType)
Enum: "BANKDDA" "IBAN" "BBAN" "CARD" "CHECK"
instrument_name
string or null <= 32 characters

Name of instrument

instrument_settlement_currency
string or null <= 3 characters

Bank account or card currency in ISO-3 character format.

instrument_category
required
string (InstrumentCategory)
Enum: "INDIVIDUAL" "CORPORATE"
instrument_usage
string or null <= 12 characters

Instrument usage. Valid values are PAY-IN, PAY-OUT, PAY-IN-OUT, RESTRICTED

mask_account_number
string or null <= 19 characters

Masked bank account number or card number.

required
object (AccountInfo)

Base class for account info

outside_iin
string or null <= 19 characters
financial_inst_name
string or null <= 32 characters

Name of the financial institution owning the external instrument. It will mostly be the bank that issued the bank account number or the card. This field is mandatory for bank instrument types

external_proxy_number
string or null <= 64 characters
instrument_verification_method
string (InstrumentVerificationMethod)
Enum: "BANK" "CARDAVV" "CARD3DS"
instrument_status
string (InstrumentStatus)
Enum: "ACTIVE" "SUSPEND" "NEGLIST" "FORGET" "UNPROVED" "REPLACED"
object (Acknowledgement)
sys_utcinserted
string <date-time>

date outside instrument created

base_outside_instrument_guid
string or null <uuid>

once outside instrument is replaced this points back to the original outside instrument with the latest information

instrument_ownership
string (InstrumentOwnership)
Enum: "SELF" "THIRDPARTY"
status_reason
string or null
Responses
201

Returns the newly created outside instrument

400

Bad request

401

Unauthorized

404

Person not found

500

Server Error

post/api/{version}/outside_instruments
Request samples
application/json
{
  • "outside_instrument_guid": "f2fb9354-2f4f-40d1-819c-4ff2a66a4bd8",
  • "person_guid": "2ae6ba4b-f6c0-4817-a158-43e5a87168fd",
  • "instrument_country": "string",
  • "instrument_type": "BANKDDA",
  • "instrument_name": "string",
  • "instrument_settlement_currency": "str",
  • "instrument_category": "INDIVIDUAL",
  • "instrument_usage": "string",
  • "mask_account_number": "string",
  • "account_details": {
    • "card_account": {
      • "card_number": "stringstrings",
      • "expiration_date": "stri",
      • "verification_code": "strin",
      • "expiry_status": "string"
      },
    • "bank_account": {
      • "account_type": "DDA",
      • "account_number": "string",
      • "routing_number": "string",
      • "rtp_routing_number": "string",
      • "bank_identifier": "string",
      • "bank_dba": "string",
      • "bank_address": {
        • "city": "string",
        • "country": "str",
        • "address_line1": "string",
        • "address_line2": "string",
        • "postal_code": "string",
        • "state": "string"
        },
      • "swift_code": "string",
      • "bank_phone": "string",
      • "description": "string",
      • "name_on_account": "string",
      • "accountholder_address": {
        • "city": "string",
        • "country": "str",
        • "address_line1": "string",
        • "address_line2": "string",
        • "postal_code": "string",
        • "state": "string"
        },
      • "additional_data": {
        • "property1": "string",
        • "property2": "string"
        }
      }
    },
  • "outside_iin": "string",
  • "financial_inst_name": "string",
  • "external_proxy_number": "string",
  • "instrument_verification_method": "BANK",
  • "instrument_status": "ACTIVE",
  • "acknowledgement": {
    • "tc_version": "string",
    • "acknowledgement_date": "string",
    • "ip_address": "string"
    },
  • "sys_utcinserted": "2019-08-24T14:15:22Z",
  • "base_outside_instrument_guid": "d06e7842-2b65-4e80-a035-958d85404833",
  • "instrument_ownership": "SELF",
  • "status_reason": "string"
}
Response samples
application/json
{
  • "outside_instrument_guid": "f2fb9354-2f4f-40d1-819c-4ff2a66a4bd8",
  • "person_guid": "2ae6ba4b-f6c0-4817-a158-43e5a87168fd",
  • "instrument_country": "string",
  • "instrument_type": "BANKDDA",
  • "instrument_name": "string",
  • "instrument_settlement_currency": "str",
  • "instrument_category": "INDIVIDUAL",
  • "instrument_usage": "string",
  • "mask_account_number": "string",
  • "account_details": {
    • "card_account": {
      • "card_number": "stringstrings",
      • "expiration_date": "stri",
      • "verification_code": "strin",
      • "expiry_status": "string"
      },
    • "bank_account": {
      • "account_type": "DDA",
      • "account_number": "string",
      • "routing_number": "string",
      • "rtp_routing_number": "string",
      • "bank_identifier": "string",
      • "bank_dba": "string",
      • "bank_address": {
        • "city": "string",
        • "country": "str",
        • "address_line1": "string",
        • "address_line2": "string",
        • "postal_code": "string",
        • "state": "string"
        },
      • "swift_code": "string",
      • "bank_phone": "string",
      • "description": "string",
      • "name_on_account": "string",
      • "accountholder_address": {
        • "city": "string",
        • "country": "str",
        • "address_line1": "string",
        • "address_line2": "string",
        • "postal_code": "string",
        • "state": "string"
        },
      • "additional_data": {
        • "property1": "string",
        • "property2": "string"
        }
      }
    },
  • "outside_iin": "string",
  • "financial_inst_name": "string",
  • "external_proxy_number": "string",
  • "instrument_verification_method": "BANK",
  • "instrument_status": "ACTIVE",
  • "acknowledgement": {
    • "tc_version": "string",
    • "acknowledgement_date": "string",
    • "ip_address": "string"
    },
  • "sys_utcinserted": "2019-08-24T14:15:22Z",
  • "base_outside_instrument_guid": "d06e7842-2b65-4e80-a035-958d85404833",
  • "instrument_ownership": "SELF",
  • "status_reason": "string"
}
Copyright © 2023 KeyBank & Qolo. All rights reserved.