Retrive account details

Published on Mar 26, 2025

13 minute(s) read

Get

/account_details

This endpoint will validate different types of account identifiers.

The query param account_format could be one of the following values: IBAN, BBAN, BIC, ABA, USABA, BSB, CNAPS, COMPE, CPA, IFSC, NZBA, SC, etc. You can see a list here: https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets (JSON file) Also, the endpoint /national_account_formats returns the format for a specific country. Check the response property 'nationalIdLocalAcronym'.

The query param account_number contains the value to validate using the correspondent format.

For 'BBAN' format the query parameter country is required.

Security

OAuth

OAuth Grant type, JWT Profile

FlowClient Credentials

Token URL$(host)/oauth/token

Scopes:

account_details.readAccessing all accounts and validating parameters

Header parameters

x-client-id

string (uuid) Required

Identifies the client of the api

Min length36

Max length36

Pattern^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

Examplea1b30a84-7bf3-442e-84a0-e935d8163b5a

Query parameters

account_format

string

Account format (such us IBAN BBAN, BIC, ABA, USABA, BSB, CNAPS, COMPE, CPA, IFSC, NZBA, SC, etc.)

Max length5

Pattern^[A-Z]*$

ExampleABA

account_number

string

Account number

Max length50

Pattern^[0-9A-Z\/\-\\()\s]*$

Example104100004048

country

string

ISO country code

Max length2

Pattern^[A-Z]{2}$

ExampleES

Responses

200

The account number provided is valid according to format and internal validations and it will return a valid message with account details for this account number.

Valid Account Details

{
  "data": {
    "isValid": true,
    "details": {
      "bankName": "CITY NATIONAL BANK",
      "bic": "CINAUS6LXXX",
      "connectedBic": "CINAUS6LXXX",
      "account": "401234567891",
      "nationalIdType": "ABA",
      "nationalId": "122016066",
      "bankAddress": {
        "city": "LOS ANGELES",
        "zipCode": "90071",
        "streetAddress": [
          "S. FLOWER STREET, 555",
          "SOUTH FLOOR 21",
          "FLOOR 23"
        ],
        "country": "UNITED STATES OF AMERICA",
        "isoCountry": "US"
      },
      "institutionStatus": "BANK",
      "networkConnectivity": "CCC",
      "subtypeIndicator": "SUPE",
      "isoLeiCode": "593C3GZG957YOJPS2Z63",
      "schemeParticipation": [
        "SNET",
        "SNETFIN",
        "US CHIPS",
        "US FEDWIR"
      ],
      "ssis": [
        {
          "currency": "AED",
          "intermediaryBic": "SCBLAEADXXX",
          "isPreferred": false,
          "platforms": [
            "AE IPI",
            "AE UAEFTS",
            "AE WPS",
            "CN CIPS",
            "EMU TGT2",
            "SNET",
            "SNETFIN",
            "US CHIPS"
          ]
        },
        {
          "currency": "AUD",
          "intermediaryBic": "NATAAU33XXX",
          "isPreferred": false,
          "platforms": [
            "AU CS",
            "AU RITS",
            "EMU E1S1",
            "EMU TGT2",
            "SNET",
            "SNETFIN"
          ]
        },
        {
          "currency": "AUD",
          "intermediaryBic": "NATAAU33XXX",
          "isPreferred": false,
          "platforms": [
            "AU CS",
            "AU RITS",
            "EMU E1S1",
            "EMU TGT2",
            "SNET",
            "SNETFIN"
          ]
        }
      ]
    }
  }
}

Expand All

object

It contains all the account details

data

object

Contains information of the process

isValid

boolean

True if account number is valid

ExampleTrue

details

object

Returns the account details

bankName

string

Account bank name

Max length250

Pattern^[A-Za-z0-9\s,.]*$

ExampleCITY NATIONAL BANK

iban

string

Account bank name

Max length50

Pattern^[0-9A-Z\s]*$

ExampleES9121000418450200051332

bban

string

Account bank name

Max length50

Pattern^[0-9A-Z\s]*$

Example21000418450200051332

bic

string

BIC

Max length11

Pattern^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$

ExampleARABMAMCXXX

connectedBic

string

BIC

Max length11

Pattern^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$

ExampleARABMAMCXXX

account

string

Account bank name

Max length50

Pattern^[\w.,\s]+$

ExampleCITY NATIONAL BANK

routingCode

object

Specific national code and national id

type

string

Routing code type

Max length10

Pattern^[A-Z]*$

ExampleABA

number

string

Account number to be used in the validations.

Max length50

Pattern^[0-9A-Z]*$

Example12345678

nationalIdType

string

General national code

Max length10

Pattern^[A-Z]*$

ExampleABA

nationalId

string

General national id

Max length50

Pattern^[0-9A-Z\/\-\\()\s]*$

Example122016066

branchId

string

General branch id

Max length50

Pattern^[0-9A-Z\/\-\\()\s]*$

Example01652

bankAddress

object

Bank full address

city

string

Bank city

Max length50

Pattern^[A-Z\s]*$

ExampleBARCELONA

zipCode

string

Bank zip code

Max length20

Pattern^[A-Za-z0-9 ]+$

Example08028

streetAddress

Array of string

Bank street address

Max items25

Example[ "Carrer Maria Barrientos", "N 25" ]

string

Street address

Max length255

Pattern^[\w.,\s]+$

ExampleCarrer Maria Barrientos

country

string

Bank country

Max length50

Pattern^[A-Z\s]*$

ExampleSPAIN

isoCountry

string

Bank ISO country code

Max length2

Pattern^[A-Z\s]*$

ExampleES

isoLeiCode

string

Bank ISO Lei Code

Max length50

Pattern^[A-Z0-9]*$

Example7CUNS533WID6K7DGFI87

institutionStatus

string

Bank institution status

Max length25

Pattern^[A-Z]*$

ExampleBANK

subtypeIndicator

string

Bank subtype indicator

Max length25

Pattern^[A-Z]*$

ExampleSUPE

networkConnectivity

string

Bank network connectivity

Max length25

Pattern^[A-Z]*$

ExampleCCC

schemeParticipation

Array of string (ClearingSchemeItem)

Bank clearing schemes

Max items25

Example[ "SNET", "SNETFIN", "US CHIPS" ]

string

Individual clearing scheme

Max length25

Pattern^[A-Z0-9\s]*$

ExampleGB CHAPS

ssis

Array of object

Bank SSI routes

Max items25

object

SSI route

currency

string

Currency ISO code

Max length3

Pattern^[A-Z]{3}$

ExampleEUR

intermediaryBic

string

BIC

Max length11

Pattern^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$

ExampleARABMAMCXXX

isPreferred

boolean

If SSI route is preferred or not

ExampleTrue

platforms

Array of string

SSI Platforms

Max items25

string

SSI Platform

Max length25

Pattern^[A-Z0-9\s]*$

ExampleCN CIPS

204

No Content

400

Bad Request

Internal Server Error

{
  "errors": [
    {
      "code": "400",
      "message": "BAD_REQUEST",
      "level": "FATAL",
      "description": "Bad request"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

401

User not authorized

User Unauthorized

{
  "errors": [
    {
      "code": "401",
      "message": "UNAUTHORIZED",
      "level": "FATAL",
      "description": "User unauthorized"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

403

Access forbidden

Forbidden

{
  "errors": [
    {
      "code": "403",
      "message": "FORBIDDEN",
      "level": "ERROR",
      "description": "Access forbidden"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

404

Not Found

NotFound

Not found

{
  "errors": [
    {
      "code": "404",
      "message": "NOT_FOUND",
      "level": "ERROR",
      "description": "Not found"
    }
  ]
}

Correspondent Delivery Date Not Found

The Correspondent was not found

{
  "errors": [
    {
      "code": "404",
      "message": "NOT_FOUND",
      "level": "ERROR",
      "description": "Correspondent could not be found"
    }
  ]
}

Account Not Found

The Requested account data is not found

{
  "errors": [
    {
      "code": "404",
      "message": "NOT_FOUND",
      "level": "ERROR",
      "description": "The requested Account Number is not a valid _accountFormat_ account"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

406

The Accept header does not specifically contains one of the allowable types, usually 'application/json'

Not Acceptable

{
  "errors": [
    {
      "code": "406",
      "message": "NOT_ACCEPTABLE",
      "level": "ERROR",
      "description": "Accept header is not application/json"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

413

Most web servers have a limit of 8192 bytes (8 KB). The server will close the connection to prevent the client from continuing the request.

Request Entity Too Large

{
  "errors": [
    {
      "code": "413",
      "message": "REQUEST_ENTITY_TOO_LARGE",
      "level": "ERROR",
      "description": "Request entity larger than 8192 bytes - 8KB"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

414

URI request is longer than 2,000 characters

URI Too Long

{
  "errors": [
    {
      "code": "414",
      "message": "URI_TOO_LONG",
      "level": "ERROR",
      "description": "URI request is longer than 2000 characters"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

422

Unprocessable Entity

Unprocessable entity

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "Unprocessable entity"
    }
  ]
}

Invalid Request Currency

The requested parameters contain an invalid Currency value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - currency - It must be present in routeParams or extraDetails pacs - IntrBkSttlmAmt.Ccy"
    }
  ]
}

Invalid Request Account Data

The requested parameters contain an invalid account format/number value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - accountFormat or accountNumber - They must be present in routeParams or extraDetails pacs - IntrmyAgt1.FinInstnId  CdtrAcct.Id.IBAN or CdtrAgt.FinInstnId"
    }
  ]
}

Invalid Request Charge Type

The requested parameters contain an invalid Charge Type value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - chargeType - No union satisfied. expected value to be literal OUR but got foobar expected value to be literal BEN but got foobar expected value to be literal SHA but got foobar"
    }
  ]
}

Invalid Request Origin Bank

The requested parameters contain an invalid Origin Bank value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - originBank - expected string to match pattern but did not"
    }
  ]
}

Invalid Request Origin Country

The requested parameters contain an invalid Origin Country value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - originCountry - expected string to match pattern but did not"
    }
  ]
}

Invalid Request Payment Amount

The requested parameters contain an invalid Payment Amount value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - paymentAmount - expected type to be number but got string"
    }
  ]
}

Invalid Request Value Percentage

The requested parameters contain an invalid Value Percentage value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - volumePercentage - expected number to be less than or equal to 100 but got 999999"
    }
  ]
}

Invalid Request Permanent Input

The requested parameters contain an invalid Permanent Input value
Permanent Inputs: sameCorrespondent, volumePercentage, searchIntermediary, commonCorrespondent.

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - sameCorrespondent - No union satisfied. expected string to be one of - true false. expected type to be boolean but got string"
    }
  ]
}

Invalid Request Clearing Scheme

The Request parameters contain an invalid Clearing Scheme value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - clearingScheme - expected string to match pattern but did not"
    }
  ]
}

Invalid Request Service Code

The Request parameters contain an invalid Service Code value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - serviceCode - expected string to match pattern but did not"
    }
  ]
}

Invalid SSI Correspondent Steps

The Request parameters contain an invalid SSI Correspondent Steps value

{
  "errors": [
    {
      "code": "422",
      "message": "UNPROCESSABLE_ENTITY",
      "level": "ERROR",
      "description": "error parsing object at path - ssiCorrespondentSteps - expected number to be less than or equal to 10 but got 11"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

429

The user has sent too many requests in a given amount of time

Too Many Requests

{
  "errors": [
    {
      "code": "429",
      "message": "TOO_MANY_REQUESTS",
      "level": "ERROR",
      "description": "Too many requests"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

500

Internal Server Error

{
  "errors": [
    {
      "code": "500",
      "message": "INTERNAL_SERVER_ERROR",
      "level": "ERROR",
      "description": "Unknown error caught in the error middleware"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

503

Service is unavailable

{
  "errors": [
    {
      "code": "503",
      "message": "SERVICE_UNAVAILABLE",
      "level": "ERROR",
      "description": "Service is unavailable"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

504

Gateway timeout

{
  "errors": [
    {
      "code": "504",
      "message": "GATEWAY_TIMEOUT",
      "level": "ERROR",
      "description": "Gateway timeout"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

default

Internal Server Error

{
  "errors": [
    {
      "code": "500",
      "message": "INTERNAL_SERVER_ERROR",
      "level": "ERROR",
      "description": "Unknown error caught in the error middleware"
    }
  ]
}

Expand All

object

Data structure containing the details for errors

errors

Array of object (Error)

Array of errors

Min items0

Max items50

object

Data structure containing the error details

code

string

Unique alphanumeric human readable error code

Min length1

Max length25

Pattern^[a-zA-Z_0-9 ]*$

ExampleXXX

message

string

Brief summary of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleMessage

level

string

Level of the reported issue. The possible values are.

ERROR
FATAL
INFO
WARNING

Valid values[ "ERROR", "FATAL", "INFO", "WARNING" ]

ExampleERROR

description

string

Detailed description of the reported issue

Min length1

Max length255

Pattern^[a-zA-Z0-9. /_-]*$

ExampleDescription

Was this article helpful?