---
title: "Check IBAN via API"
description: "This integration method is via API. It will therefore be sufficient to implement the following API:"
url: "https://docs.fabrick.com/en/payment-institution/banking-as-a-service/check-iban/dev/check-iban-api/"
language: "en"
---

# Check IBAN via API

This integration method is via API. It will therefore be sufficient to implement the following API:

```text
POST {domain}/v4.0/banking-services/account-holders/validate
Auth-Schema: S2S
Apikey: [apiKey]
Content-Type: application/json

{
  "account": {
    "value": "XX00A0000011111200ALWAYSOK",
    "valueType": "IBAN"
  },
  "accountHolder": {
    "type": "PERSON_NATURAL",
    "fiscalCode": "RSSPLA00A28A859V"
  }
}
```

where:

- *account*: JSON object containing account information.

- *value*: the IBAN for which ownership is to be verified.

- *valueType*: input type; currently, the only permitted value is "*IBAN*".

- *accountHolder*: JSON object containing information about the account holder.

  - *fiscalCode*: the tax code of the account holder, in the case of a natural person. This field requires an Italian tax code. Required if *accountHolder.type* = *PERSON_NATURAL*.
  - *vatCode*: the VAT code of the account holder, in the case of a legal entity. This field requires an Italian VAT number. Required if *accountHolder.type* = *PERSON_LEGAL*.
  - *taxCode*: the tax code of the account holder, in the case of a legal entity. This field requires an Italian company tax code or an Italian tax code (if the legal entity is an Italian "sole proprietorship" or "freelancer"). Required if *accountHolder.type* = *PERSON_LEGAL*.
  - *type*: the type of account holder. Valid values are *PERSON_NATURAL* for a natural person or *PERSON_LEGAL* for a legal entity (in the form of a company or Italian "sole proprietorship" or "freelancer").

The response will be:

```json
{
  "status": "OK",
  "payload": {
    "validationStatus": "OK",
    "account": {
      "value": "XX00A0000011111200ALWAYSOK",
      "valueType": "IBAN",
      "bicCode": null
    },
    "accountHolder": {
      "type": "PERSON_NATURAL",
      "fiscalCode": "RSSPLA00A28A859V",
      "vatCode": null,
      "taxCode": null
    },
    "bankInfo": null
  },
  "errors": [],
  "warnings": null
}
```

where the *account* and *accountHolder* objects are the same objects provided in the request, while the *bankInfo* object contains information about the bank at which the account is held:

- *businessName*: name of the bank.
- *city*: city where the bank is headquartered.
- *countryCode*: ISO 3166-1 alpha-2 country code.
- *bicCode*: BIC code of the bank.
- *branchName*: bank branch.

Finally, the *validationStatus* object indicates the outcome of the verification between the account holder and the IBAN:

- *OK*: the bank confirms the correspondence.
- *KO*: the bank does not confirm the correspondence.

### Bank List

To view the list of banks available for the Check IBAN service, simply call the following API:

```http
POST /v4.0/banking-services/account-holders/psps/search
Auth-Schema: S2S
Apikey: {{apiKey}}
Content-Type: application/json

{}
```

It is also possible to apply filters via the request body:

```json
{
  "nationalCode": "12345",
  "bicCode": "ABXXXXXX",
  "countryCode": "IT",
  "name": "PSP name",
  "accountValueType": "IBAN"
}
```

where:

- *nationalCode*: national code of the PSP.
- *bicCode*: BIC code of the PSP.
- *countryCode*: ISO 3166-1 alpha-2 country code.
- *name*: name of the PSP.
- *accountValueType*: currently a constant with value *IBAN*.

The response will contain the list of available banks as shown in the following example, and each element will contain the information described above:

```json
{
  "status": "OK",
  "payload": {
    "list": [
      {
        "nationalCode": "36772",
        "bicCode": "HYEEIT22XXX",
        "countryCode": "IT",
        "name": "HYPE S.P.A.",
        "accountValueType": "IBAN"
      },
      ...
      {
        "nationalCode": "08440",
        "bicCode": "CRCBIT22XXX",
        "countryCode": "IT",
        "name": "Banca di Credito Cooperativo di Carate Brianza",
        "accountValueType": "IBAN"
      }
    ],
    "pagination": {
      "pageCount": 7,
      "resultCount": 137,
      "offset": 0,
      "limit": 20
    },
    "sorting": null
  },
  "errors": [],
  "warnings": null
}
```

#### Pagination

This section describes the pagination mechanism.

##### Request

Where available, pagination is managed via query parameters in the HTTP request:

```text
<URI>?offset={offset}&limit={limit}&pagination={pagination}
```

where:

- *offset*: this is the index (0-based) of the first element to be returned; it must be a positive integer. The default value is 0. If `offset >= resultCount`, the response will be empty, while if `offset < 0`, HTTP 400 – Bad Request will be returned.
- *limit*: indicates the maximum number of elements to return; it must be a positive integer. The default value is 20. If *limit* < 0, HTTP 400 – Bad Request is returned.

##### Response

If pagination is requested, the response will include the *pagination* object:

```json
{
  …
  "pagination": {
    "pageCount": 50,
    "resultCount": 495,
    "offset": 0,
    "limit": 10
  }
}
```

where:

- *pageCount*: indicates the total number of pages, assuming that each page contains a number of elements equal to the *limit* parameter.
- *resultCount*: indicates the total number of elements available in the results.
- *offset*: see Request.
- *limit*: see Request.