---
updatedAt: 2026-09-10T13:20:47.000Z
agentTools:
  projectIndex: https://docs.instantcashworldwide.com/llms.txt
---

# Get States

Returns a list of states which belong to a specific country.
            
If the `countryCode` is not specified, all states will be returned.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Instant Cash API Sandbox",
    "description": "Help your customers send and receive money efficiently, securely, and seamlessly to millions of global endpoints within Instant Cash.",
    "version": "v1.0"
  },
  "servers": [
    {
      "url": "https://api.instantcashworldwide.ae/sandbox"
    }
  ],
  "paths": {
    "/api/v1/states": {
      "get": {
        "tags": [
          "Sender"
        ],
        "summary": "Get States",
        "description": "Returns a list of states which belong to a specific country.\r\n            \r\nIf the `countryCode` is not specified, all states will be returned.",
        "operationId": "GetList_9d6230a5-54bc-4103-8ce2-db64db5a406c",
        "parameters": [
          {
            "name": "countryCode",
            "in": "query",
            "description": "ISO-3166 alpha-2 code. (Optional)\r\nIf it is set, only the specified country states will be returned.",
            "schema": {
              "type": "string",
              "description": "ISO-3166 alpha-2 code. (Optional)\r\nIf it is set, only the specified country states will be returned.",
              "nullable": true
            }
          },
          {
            "name": "payoutCurrency",
            "in": "query",
            "description": "Payout Currency. Use Standard ISO Currency Code.",
            "required": false,
            "schema": {
              "minLength": 3,
              "maxLength": 3,
              "type": "string",
              "description": "ISO Currency Code. (Optional, mandatory when Country is passed)\r\n\nFormat: ISO-4217 alpha-3 code.",
              "example": "INR",
              "nullable": true
            },
            "example": "INR"
          },
          {
            "name": "pageNumber",
            "in": "query",
            "description": "The number of the next page.\r\n(Default is 1)",
            "schema": {
              "maximum": 2147483647,
              "minimum": 1,
              "type": "integer",
              "description": "The number of the next page.\r\n(Default is 1)",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "This is the maximum number of records per page that can be returned to the client.\r\nMust be between 1 and 1000. (Default is 50)",
            "schema": {
              "maximum": 1000,
              "minimum": 1,
              "type": "integer",
              "description": "This is the maximum number of records per page that can be returned to the client.\r\nMust be between 1 and 1000. (Default is 50)",
              "format": "int32"
            }
          },
          {
            "name": "x-fapi-financial-id",
            "in": "header",
            "description": "This is the agent correspondent id provided to the agent by the IC Operations department. It is used to facilitate API management and auditing.",
            "required": true,
            "schema": {
              "title": "agent code",
              "pattern": "^[A-Z]{2}[0-9A-Z]{4}$",
              "type": "string"
            },
            "example": "AEXXXX"
          },
          {
            "name": "x-correlation-id",
            "in": "header",
            "description": "This header is used to uniquely identify the HTTP request and to facilitate troubleshooting.",
            "schema": {
              "title": "uuid v4",
              "pattern": "\\w{8}-\\w{4}-\\w{4}-\\w{4}-\\w{12}",
              "type": "string"
            },
            "example": "351f7184-16e4-4aca-a678-f6e623f762e4"
          },
          {
            "name": "x-idempotency-key",
            "in": "header",
            "description": "Unique request identifier to support idempotency. You may generate (UUID v4) value using the programming language.",
            "schema": {
              "title": "uuid v4",
              "pattern": "\\w{8}-\\w{4}-\\w{4}-\\w{4}-\\w{12}",
              "type": "string"
            },
            "example": "0053c524-c105-4441-aa60-38ef0261fd06"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StateGetListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ServiceError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          },
          "details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceErrorDetail"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ServiceErrorDetail": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ServiceErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ServiceError"
          }
        },
        "additionalProperties": false
      },
      "StateGetListResponse": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "integer",
            "description": "Current page number.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "This is the maximum number of records per page that can be returned to the client.",
            "format": "int32"
          },
          "total": {
            "type": "integer",
            "description": "The total number of records found in the Instant Cash database for your query.",
            "format": "int32"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StateItemModel"
            },
            "description": "A list of results.",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "StateItemModel": {
        "required": [
          "countryCode",
          "stateCode",
          "stateName"
        ],
        "type": "object",
        "properties": {
          "stateName": {
            "type": "string",
            "description": "Name of the state in English",
            "example": "Bihar"
          },
          "stateCode": {
            "type": "string",
            "description": "Specific local code of the exact state",
            "example": "10"
          },
          "countryCode": {
            "type": "string",
            "description": "Country where the exact state is included\r\n<br>Format: ISO-3166 alpha-2 code.",
            "example": "IN"
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "apiKey",
        "description": "Authorization header using the Bearer/Basic scheme. Example: \"Authorization: **{Scheme}** {token}\"",
        "name": "Authorization",
        "in": "header",
        "x-default": "Basic dXNlcl9pZDpwYXNzd29yZA=="
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "metrics-enabled": false
  }
}
```