# Country States Codes Endpoint

## Country States Codes Endpoint

<mark style="color:blue;">`GET`</mark> `https://api-stg.onekeypayments.com/v3/states?country={ISO_CODE}`

This API allows you to retrieve the list of ISO codes and the names of the states available in each country, allowing you to dynamically retrieve those on your front-end.

#### Query Parameters

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| country | string | Country ISO code |

#### Headers

| Name          | Type   | Description                                                  |
| ------------- | ------ | ------------------------------------------------------------ |
| Authorization | string | Authorization Header. Format: "Bearer your\_read\_only\_key" |

{% tabs %}
{% tab title="200 Bank list successfully retrieved" %}

```java
[
    {
        "iso": "AC",
        "name": "Acre"
    },
    {
        "iso": "AL",
        "name": "Alagoas"
    },
    {
        "iso": "AM",
        "name": "Amazonas"
    },
    {
        "iso": "AP",
        "name": "Amapá"
    },
    {
        "iso": "BA",
        "name": "Bahia"
    },
    {
        "iso": "CE",
        "name": "Ceará"
    },
    {
        "iso": "DF",
        "name": "Distrito Federal"
    },
    {
        "iso": "ES",
        "name": "Espírito Santo"
    },
    {
        "iso": "GO",
        "name": "Goiás"
    },
    {
        "iso": "MA",
        "name": "Maranhão"
    },
    {
        "iso": "MG",
        "name": "Minas Gerais"
    },
    {
        "iso": "MS",
        "name": "Mato Grosso do Sul"
    },
    {
        "iso": "MT",
        "name": "Mato Grosso"
    },
    {
        "iso": "PA",
        "name": "Pará"
    },
    {
        "iso": "PB",
        "name": "Paraíba"
    },
    {
        "iso": "PE",
        "name": "Pernambuco"
    },
    {
        "iso": "PI",
        "name": "Piauí"
    },
    {
        "iso": "PR",
        "name": "Paraná"
    },
    {
        "iso": "RJ",
        "name": "Rio de Janeiro"
    },
    {
        "iso": "RN",
        "name": "Rio Grande do Norte"
    },
    {
        "iso": "RO",
        "name": "Rondônia"
    },
    {
        "iso": "RR",
        "name": "Roraima"
    },
    {
        "iso": "RS",
        "name": "Rio Grande do Sul"
    },
    {
        "iso": "SC",
        "name": "Santa Catarina"
    },
    {
        "iso": "SE",
        "name": "Sergipe"
    },
    {
        "iso": "SP",
        "name": "São Paulo"
    },
    {
        "iso": "TO",
        "name": "Tocantins"
    }
]
```

{% endtab %}

{% tab title="401 Invalid credentials error" %}

```java
{
    "code": 100,
    "description": "Invalid credentials",
    "type": "INVALID_CREDENTIALS"
}
```

{% endtab %}
{% endtabs %}

## Introduction

This endpoint is used to retrieve and display to your customer the list of States available on their country. In case we add or remove a State, this endpoint will reflect those updates real-time and, therefore, it is a good idea to constantly check this endpoint for the list of banks.

Once the user selected their State by its name (For example on a dropdown), you need to send its code to us in the `payer.address.state` field of the deposits requests.

The endpoint is read only and so it uses a read only API Key. It can even be used from the front-end without major security concerns.

## Bank Codes Request

### Request Example

```java
// URL
GET: https://api-stg.onekeypayments.com/v3/states?country=BR

// HEADERS
Authorization: Bearer EKiFOWiHnI 
```

### Request Fields

| Type        | Field           | Format             | Description                                                                                                             |
| ----------- | --------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Query Param | `country`       | String (length: 2) | [Country ISO code](https://apidocs.onekeypayments.com/knowledge-base/countries-specifications#countries-and-currencies) |
| Header      | `Authorization` | String             | Bearer Token Authentication. It is a concatenation of the word "Bearer " and your Read Only API Key.                    |

## Bank Codes Response

### Response Example

{% tabs %}
{% tab title="Brazil" %}

```java
[
    {
        "iso": "AC",
        "name": "Acre"
    },
    {
        "iso": "AL",
        "name": "Alagoas"
    },
    {
        "iso": "AM",
        "name": "Amazonas"
    },
    {
        "iso": "AP",
        "name": "Amapá"
    },
    {
        "iso": "BA",
        "name": "Bahia"
    },
    {
        "iso": "CE",
        "name": "Ceará"
    },
    {
        "iso": "DF",
        "name": "Distrito Federal"
    },
    {
        "iso": "ES",
        "name": "Espírito Santo"
    },
    {
        "iso": "GO",
        "name": "Goiás"
    },
    {
        "iso": "MA",
        "name": "Maranhão"
    },
    {
        "iso": "MG",
        "name": "Minas Gerais"
    },
    {
        "iso": "MS",
        "name": "Mato Grosso do Sul"
    },
    {
        "iso": "MT",
        "name": "Mato Grosso"
    },
    {
        "iso": "PA",
        "name": "Pará"
    },
    {
        "iso": "PB",
        "name": "Paraíba"
    },
    {
        "iso": "PE",
        "name": "Pernambuco"
    },
    {
        "iso": "PI",
        "name": "Piauí"
    },
    {
        "iso": "PR",
        "name": "Paraná"
    },
    {
        "iso": "RJ",
        "name": "Rio de Janeiro"
    },
    {
        "iso": "RN",
        "name": "Rio Grande do Norte"
    },
    {
        "iso": "RO",
        "name": "Rondônia"
    },
    {
        "iso": "RR",
        "name": "Roraima"
    },
    {
        "iso": "RS",
        "name": "Rio Grande do Sul"
    },
    {
        "iso": "SC",
        "name": "Santa Catarina"
    },
    {
        "iso": "SE",
        "name": "Sergipe"
    },
    {
        "iso": "SP",
        "name": "São Paulo"
    },
    {
        "iso": "TO",
        "name": "Tocantins"
    }
]
```

{% endtab %}

{% tab title="Colombia" %}

```java
[
    {
        "iso": "AMA",
        "name": "Amazonas"
    },
    {
        "iso": "ANT",
        "name": "Antioquia"
    },
    {
        "iso": "ARA",
        "name": "Arauca"
    },
    {
        "iso": "ATL",
        "name": "Atlántico"
    },
    {
        "iso": "BOL",
        "name": "Bolívar"
    },
    {
        "iso": "BOY",
        "name": "Boyacá"
    },
    {
        "iso": "CAL",
        "name": "Caldas"
    },
    {
        "iso": "CAQ",
        "name": "Caquetá"
    },
    {
        "iso": "CAS",
        "name": "Casanare"
    },
    {
        "iso": "CAU",
        "name": "Cauca"
    },
    {
        "iso": "CES",
        "name": "Cesar"
    },
    {
        "iso": "CHO",
        "name": "Chocó"
    },
    {
        "iso": "COR",
        "name": "Córdoba"
    },
    {
        "iso": "CUN",
        "name": "Cundinamarca"
    },
    {
        "iso": "GUA",
        "name": "Guainía"
    },
    {
        "iso": "GUV",
        "name": "Guaviare"
    },
    {
        "iso": "HUI",
        "name": "Huila"
    },
    {
        "iso": "LAG",
        "name": "La Guajira"
    },
    {
        "iso": "MAG",
        "name": "Magdalena"
    },
    {
        "iso": "MET",
        "name": "Meta"
    },
    {
        "iso": "NAR",
        "name": "Nariño"
    },
    {
        "iso": "NSA",
        "name": "Norte de Santander"
    },
    {
        "iso": "PUT",
        "name": "Putumayo"
    },
    {
        "iso": "QUI",
        "name": "Quindío"
    },
    {
        "iso": "RIS",
        "name": "Risaralda"
    },
    {
        "iso": "SAN",
        "name": "Santander"
    },
    {
        "iso": "SAP",
        "name": "San Andrés y Providencia"
    },
    {
        "iso": "SUC",
        "name": "Sucre"
    },
    {
        "iso": "TOL",
        "name": "Tolima"
    },
    {
        "iso": "VAC",
        "name": "Valle del Cauca"
    },
    {
        "iso": "VAU",
        "name": "Vaupés"
    },
    {
        "iso": "VID",
        "name": "Vichada"
    }
]
```

{% endtab %}
{% endtabs %}

### **Response fields**

| Field  | Format                          | Description                                                                                                                                                                                                                                                                                  |
| ------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iso`  | String (length between 1 and 3) | State code in [*ISO 3166-2* format](https://en.wikipedia.org/wiki/ISO_3166-2). It is the value you must send in the `payer.address.state` field of the [Deposits requests](https://apidocs.onekeypayments.com/api-documentation/deposits-api/deposit-creation-endpoint#payer-address-object) |
| `name` | String                          | Name of the State                                                                                                                                                                                                                                                                            |