# 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](/knowledge-base/countries-specifications.md#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](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint.md#payer-address-object) |
| `name` | String                          | Name of the State                                                                                                                                                                                                                                                       |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/country-states-codes-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.