# States list This endpoint provides standardized state information for use in address forms, geographic filtering, and regional data management. **Endpoint** `GET/v2/geo/state` **Link** {% embed url="" %} ### **Request** #### **Headers** | Key | Value | Required | | --------------- | ------------------ | -------- | | `Authorization` | `123` | Yes | | `Accept` | `application/json` | Yes | #### **Query Parameters** | Parameter | Type | Description | Required | Example | | ------------------- | --------- | --------------------------------------------- | -------- | -------------- | | **`filter`** | `string` | **Optional filter** for state names or codes. | No | `"california"` | | **`meta.page`** | `integer` | **Page number** (starts from 0). | No | `0` | | **`meta.pageSize`** | `integer` | **Items count per page**. | No | `50` | *** ### **Response (200 OK)** Returns a paginated list of state/region objects with geographic identifiers and pagination metadata. #### **Response Fields** **Items Array** Array of state objects with the following structure: | Field | Type | Description | Example | | ---------- | --------- | ------------------------------------------ | -------------- | | **`id`** | `integer` | **Unique state ID**. | `5` | | **`iso`** | `string` | **ISO country code** the state belongs to. | `"US"` | | **`code`** | `string` | **State/region code** (abbreviation). | `"CA"` | | **`name`** | `string` | **Full state/region name**. | `"California"` | **Meta Object** Pagination metadata for the response: | Field | Type | Description | Example | | -------------- | --------- | ------------------------------------------- | ------- | | **`pageSize`** | `integer` | **Number of items per page**. | `50` | | **`page`** | `integer` | **Current page number** (0-based). | `0` | | **`total`** | `string` | **Total number of items** across all pages. | `"50"` | *** ### **Examples** #### **Request (All States with Pagination)** bash ``` curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state?meta.page=0&meta.pageSize=10' \ -H 'Authorization: 123' \ -H 'Accept: application/json' ``` #### **Response** json ``` { "items": [ { "id": 1, "iso": "US", "code": "AL", "name": "Alabama" }, { "id": 2, "iso": "US", "code": "AK", "name": "Alaska" }, { "id": 3, "iso": "US", "code": "AZ", "name": "Arizona" }, { "id": 4, "iso": "US", "code": "AR", "name": "Arkansas" }, { "id": 5, "iso": "US", "code": "CA", "name": "California" }, { "id": 6, "iso": "US", "code": "CO", "name": "Colorado" }, { "id": 7, "iso": "US", "code": "CT", "name": "Connecticut" }, { "id": 8, "iso": "US", "code": "DE", "name": "Delaware" }, { "id": 9, "iso": "US", "code": "FL", "name": "Florida" }, { "id": 10, "iso": "US", "code": "GA", "name": "Georgia" } ], "meta": { "pageSize": 10, "page": 0, "total": "50" } } ``` #### **Request (Filtered by Name)** bash ``` curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state?filter=new&meta.page=0&meta.pageSize=5' \ -H 'Authorization: 123' \ -H 'Accept: application/json' ``` #### **Response (Filtered)** json ``` { "items": [ { "id": 31, "iso": "US", "code": "NH", "name": "New Hampshire" }, { "id": 32, "iso": "US", "code": "NJ", "name": "New Jersey" }, { "id": 33, "iso": "US", "code": "NM", "name": "New Mexico" }, { "id": 34, "iso": "US", "code": "NY", "name": "New York" }, { "id": 46, "iso": "GB", "code": "NIR", "name": "Northern Ireland" } ], "meta": { "pageSize": 5, "page": 0, "total": "5" } } ``` #### **Request (Filtered by Code)** bash ``` curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state?filter=ca&meta.page=0&meta.pageSize=10' \ -H 'Authorization: 123' \ -H 'Accept: application/json' ``` #### **Response (Code Filter)** json ``` { "items": [ { "id": 5, "iso": "US", "code": "CA", "name": "California" }, { "id": 51, "iso": "CA", "code": "AB", "name": "Alberta" }, { "id": 52, "iso": "CA", "code": "BC", "name": "British Columbia" }, { "id": 53, "iso": "CA", "code": "MB", "name": "Manitoba" } ], "meta": { "pageSize": 10, "page": 0, "total": "4" } } ``` #### **Request (Default Pagination)** bash ``` curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state' \ -H 'Authorization: 123' \ -H 'Accept: application/json' ``` #### **Response (Default)** json ``` { "items": [ { "id": 1, "iso": "US", "code": "AL", "name": "Alabama" }, { "id": 2, "iso": "US", "code": "AK", "name": "Alaska" }, { "id": 3, "iso": "US", "code": "AZ", "name": "Arizona" }, { "id": 4, "iso": "US", "code": "AR", "name": "Arkansas" }, { "id": 5, "iso": "US", "code": "CA", "name": "California" } ], "meta": { "pageSize": 50, "page": 0, "total": "50" } } ``` *** ### **Error Responses** 1. **Invalid Page Parameters**: json ``` { "error": "Invalid page parameters: page must be >= 0" } ``` 2. **Unauthorized**: json ``` { "error": "Unauthorized" } ``` 3. **Rate Limit Exceeded**: json ``` { "error": "Rate limit exceeded" } ``` *** ### **Notes** * **Pagination**: Default page size is typically 50 items if not specified * **Filtering**: The `filter` parameter searches both state names and codes * **International Support**: Includes states/regions from multiple countries (US, CA, GB, etc.) * **ISO Codes**: Uses standard ISO 3166 country codes * **Sorting**: Results are typically sorted by country ISO code and state name * **Performance**: Efficient for dropdown population and geographic data management **Common Use Cases**: * Address form state/region dropdowns * Geographic filtering and reporting * Regional data analysis * Compliance with geographic requirements * Multi-country application support **Filter Behavior**: * Case-insensitive search * Matches partial names and codes * Searches across all countries * Returns results from any matching field (name or code) Real request example ```postman_json Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjE2NCwiZXhwIjoxNzYxMTM1OTI3LCJrZXkiOiI1Y2ZiOGZjN2RmYjk4ZjVkYmIyZTgwNTVkZWFhN2U2Zjk4MzEyYmE3Iiwib3RwX3ZlcmlmaWVkIjpmYWxzZX0.bvY7rDxLEZGnuZ8WcyMlqB-VQKeKCRCVTM5UZYPRQzg ``` Real response example 200 OK ```postman_json { "items": [ { "id": 1, "iso": "AZ", "code": "KALBAJAR", "name": "Kalbajar" }, { "id": 2, "iso": "AZ", "code": "SHUSHA", "name": "Shusha" }, { "id": 3, "iso": "AZ", "code": "TARTAR", "name": "Tartar" }, { "id": 4, "iso": "AZ", "code": "KHOJALY", "name": "Khojaly" }, { "id": 5, "iso": "AZ", "code": "KHOJAVEND", "name": "Khojavend" }, { "id": 6, "iso": "AZ", "code": "ABSHERON", "name": "Absheron" }, { "id": 7, "iso": "AZ", "code": "AGHJABADI", "name": "Aghjabadi" }, { "id": 8, "iso": "AZ", "code": "AGHDAM", "name": "Aghdam" }, { "id": 9, "iso": "AZ", "code": "AGDASH", "name": "Agdash" }, { "id": 10, "iso": "AZ", "code": "AGHSTAFA", "name": "Aghstafa" }, { "id": 11, "iso": "AZ", "code": "AGSU", "name": "Agsu" }, { "id": 12, "iso": "AZ", "code": "SIRVAN", "name": "Sirvan" }, { "id": 13, "iso": "AZ", "code": "ASTARA", "name": "Astara" }, { "id": 14, "iso": "AZ", "code": "BAKU", "name": "Baku" }, { "id": 15, "iso": "AZ", "code": "BALAKAN", "name": "Balakan" }, { "id": 16, "iso": "AZ", "code": "BARDA", "name": "Barda" }, { "id": 17, "iso": "AZ", "code": "BEYLAGAN", "name": "Beylagan" }, { "id": 18, "iso": "AZ", "code": "BILASUVAR", "name": "Bilasuvar" }, { "id": 19, "iso": "AZ", "code": "JABRAYIL", "name": "Jabrayil" }, { "id": 20, "iso": "AZ", "code": "JALILABAD", "name": "Jalilabad" }, { "id": 21, "iso": "AZ", "code": "DASHKASAN", "name": "Dashkasan" }, { "id": 22, "iso": "AZ", "code": "SHABRAN", "name": "Shabran" }, { "id": 23, "iso": "AZ", "code": "FUZULI", "name": "Fuzuli" }, { "id": 24, "iso": "AZ", "code": "GADABAY", "name": "Gadabay" }, { "id": 25, "iso": "AZ", "code": "GANJA", "name": "Ganja" }, { "id": 26, "iso": "AZ", "code": "GORANBOY", "name": "Goranboy" }, { "id": 27, "iso": "AZ", "code": "GOYCHAY", "name": "Goychay" }, { "id": 28, "iso": "AZ", "code": "HAJIGABUL", "name": "Hajigabul" }, { "id": 29, "iso": "AZ", "code": "IMISHLI", "name": "Imishli" }, { "id": 30, "iso": "AZ", "code": "ISMAYILLI", "name": "Ismayilli" }, { "id": 31, "iso": "AZ", "code": "KURDAMIR", "name": "Kurdamir" }, { "id": 32, "iso": "AZ", "code": "LACHIN", "name": "Lachin" }, { "id": 33, "iso": "AZ", "code": "LANKARAN", "name": "Lankaran" }, { "id": 34, "iso": "AZ", "code": "LERIK", "name": "Lerik" }, { "id": 35, "iso": "AZ", "code": "MASALLY", "name": "Masally" }, { "id": 36, "iso": "AZ", "code": "MINGACHEVIR", "name": "Mingachevir" }, { "id": 37, "iso": "AZ", "code": "NAFTALAN", "name": "Naftalan" }, { "id": 38, "iso": "AZ", "code": "NEFTCHALA", "name": "Neftchala" }, { "id": 39, "iso": "AZ", "code": "OGHUZ", "name": "Oghuz" }, { "id": 40, "iso": "AZ", "code": "QABALA", "name": "Qabala" }, { "id": 41, "iso": "AZ", "code": "QAKH", "name": "Qakh" }, { "id": 42, "iso": "AZ", "code": "QAZAX", "name": "Qazax" }, { "id": 43, "iso": "AZ", "code": "GOBUSTAN", "name": "Gobustan" }, { "id": 44, "iso": "AZ", "code": "QUBA", "name": "Quba" }, { "id": 45, "iso": "AZ", "code": "QUBADLI", "name": "Qubadli" }, { "id": 46, "iso": "AZ", "code": "QUSAR", "name": "Qusar" }, { "id": 47, "iso": "AZ", "code": "SAATLY", "name": "Saatly" }, { "id": 48, "iso": "AZ", "code": "SABIRABAD", "name": "Sabirabad" }, { "id": 49, "iso": "AZ", "code": "SHAKI", "name": "Shaki" }, { "id": 50, "iso": "AZ", "code": "SALYAN", "name": "Salyan" }, { "id": 51, "iso": "AZ", "code": "SHAMAKHI", "name": "Shamakhi" }, { "id": 52, "iso": "AZ", "code": "SHAMKIR", "name": "Shamkir" }, { "id": 53, "iso": "AZ", "code": "SAMUKH", "name": "Samukh" }, { "id": 54, "iso": "AZ", "code": "SIYAZAN", "name": "Siyazan" }, { "id": 55, "iso": "AZ", "code": "SUMGAIT", "name": "Sumgait" }, { "id": 56, "iso": "AZ", "code": "TOVUZ", "name": "Tovuz" }, { "id": 57, "iso": "AZ", "code": "UJAR", "name": "Ujar" }, { "id": 58, "iso": "AZ", "code": "KHACHMAZ", "name": "Khachmaz" }, { "id": 59, "iso": "AZ", "code": "KHANKENDI", "name": "Khankendi" }, { "id": 60, "iso": "AZ", "code": "GOYGOL", "name": "Goygol" }, { "id": 61, "iso": "AZ", "code": "KHIZI", "name": "Khizi" }, { "id": 62, "iso": "AZ", "code": "YARDIMLI", "name": "Yardimli" }, { "id": 63, "iso": "AZ", "code": "YEVLAKH", "name": "Yevlakh" }, { "id": 64, "iso": "AZ", "code": "ZANGILAN", "name": "Zangilan" }, { "id": 65, "iso": "AZ", "code": "ZAGATALA", "name": "Zagatala" }, { "id": 66, "iso": "AZ", "code": "ZARDAB", "name": "Zardab" }, { "id": 67, "iso": "US", "code": "AL", "name": "Alabama" }, { "id": 68, "iso": "US", "code": "AK", "name": "Alaska" }, { "id": 69, "iso": "US", "code": "AZ", "name": "Arizona" }, { "id": 70, "iso": "US", "code": "AR", "name": "Arkansas" }, { "id": 71, "iso": "US", "code": "CA", "name": "California" }, { "id": 72, "iso": "US", "code": "CO", "name": "Colorado" }, { "id": 73, "iso": "US", "code": "CT", "name": "Connecticut" }, { "id": 74, "iso": "US", "code": "DE", "name": "Delaware" }, { "id": 75, "iso": "US", "code": "FL", "name": "Florida" }, { "id": 76, "iso": "US", "code": "GA", "name": "Georgia" }, { "id": 77, "iso": "US", "code": "HI", "name": "Hawaii" }, { "id": 78, "iso": "US", "code": "ID", "name": "Idaho" }, { "id": 79, "iso": "US", "code": "IL", "name": "Illinois" }, { "id": 80, "iso": "US", "code": "IN", "name": "Indiana" }, { "id": 81, "iso": "US", "code": "IA", "name": "Iowa" }, { "id": 82, "iso": "US", "code": "KS", "name": "Kansas" }, { "id": 83, "iso": "US", "code": "KY", "name": "Kentucky" }, { "id": 84, "iso": "US", "code": "LA", "name": "Louisiana" }, { "id": 85, "iso": "US", "code": "ME", "name": "Maine" }, { "id": 86, "iso": "US", "code": "MD", "name": "Maryland" }, { "id": 87, "iso": "US", "code": "MA", "name": "Massachusetts" }, { "id": 88, "iso": "US", "code": "MI", "name": "Michigan" }, { "id": 89, "iso": "US", "code": "MN", "name": "Minnesota" }, { "id": 90, "iso": "US", "code": "MS", "name": "Mississippi" }, { "id": 91, "iso": "US", "code": "MO", "name": "Missouri" }, { "id": 92, "iso": "US", "code": "MT", "name": "Montana" }, { "id": 93, "iso": "US", "code": "NE", "name": "Nebraska" }, { "id": 94, "iso": "US", "code": "NV", "name": "Nevada" }, { "id": 95, "iso": "US", "code": "NH", "name": "New Hampshire" }, { "id": 96, "iso": "US", "code": "NJ", "name": "New Jersey" }, { "id": 97, "iso": "US", "code": "NM", "name": "New Mexico" }, { "id": 98, "iso": "US", "code": "NY", "name": "New York" }, { "id": 99, "iso": "US", "code": "NC", "name": "North Carolina" }, { "id": 100, "iso": "US", "code": "ND", "name": "North Dakota" }, { "id": 101, "iso": "US", "code": "OH", "name": "Ohio" }, { "id": 102, "iso": "US", "code": "OK", "name": "Oklahoma" }, { "id": 103, "iso": "US", "code": "OR", "name": "Oregon" }, { "id": 104, "iso": "US", "code": "PA", "name": "Pennsylvania" }, { "id": 105, "iso": "US", "code": "RI", "name": "Rhode Island" }, { "id": 106, "iso": "US", "code": "SC", "name": "South Carolina" }, { "id": 107, "iso": "US", "code": "SD", "name": "South Dakota" }, { "id": 108, "iso": "US", "code": "TN", "name": "Tennessee" }, { "id": 109, "iso": "US", "code": "TX", "name": "Texas" }, { "id": 110, "iso": "US", "code": "UT", "name": "Utah" }, { "id": 111, "iso": "US", "code": "VT", "name": "Vermont" }, { "id": 112, "iso": "US", "code": "VA", "name": "Virginia" }, { "id": 113, "iso": "US", "code": "WA", "name": "Washington" }, { "id": 114, "iso": "US", "code": "WV", "name": "West Virginia" }, { "id": 115, "iso": "US", "code": "WI", "name": "Wisconsin" }, { "id": 116, "iso": "US", "code": "WY", "name": "Wyoming" }, { "id": 117, "iso": "CY", "code": "LEFKOSA", "name": "Lefkosa" }, { "id": 118, "iso": "CY", "code": "GAZIMAGUSA", "name": "Gazimagusa" }, { "id": 119, "iso": "CY", "code": "GIRNE", "name": "Girne" }, { "id": 120, "iso": "CY", "code": "GUZELYURT", "name": "Guzelyurt" }, { "id": 121, "iso": "CY", "code": "ISKELE", "name": "Iskele" }, { "id": 122, "iso": "CY", "code": "LEFKE", "name": "Lefke" }, { "id": 123, "iso": "CY", "code": "FAMAGUSTA", "name": "Famagusta" }, { "id": 124, "iso": "CY", "code": "KYRENIA", "name": "Kyrenia" }, { "id": 125, "iso": "CY", "code": "LARNACA", "name": "Larnaca" }, { "id": 126, "iso": "CY", "code": "LIMASSOL", "name": "Limassol" }, { "id": 127, "iso": "CY", "code": "NICOSIA", "name": "Nicosia" }, { "id": 128, "iso": "CY", "code": "PAPHOS", "name": "Paphos" }, { "id": 129, "iso": "GE", "code": "TBILISI", "name": "Tbilisi" }, { "id": 130, "iso": "GE", "code": "IMERETI", "name": "Imereti" }, { "id": 131, "iso": "GE", "code": "AJARIA", "name": "Ajaria" }, { "id": 132, "iso": "GE", "code": "KVEMO_KARTLI", "name": "Kvemo Kartli" }, { "id": 133, "iso": "GE", "code": "SAMEGRELO_ZEMO_SVANETI", "name": "Samegrelo and Zemo Svaneti" }, { "id": 134, "iso": "GE", "code": "KAKHETI", "name": "Kakheti" }, { "id": 135, "iso": "GE", "code": "SHIDA_KARTLI", "name": "Shida Kartli" }, { "id": 136, "iso": "GE", "code": "ABKHAZIA", "name": "Abkhazia" }, { "id": 137, "iso": "GE", "code": "SAMTSKHE_JAVAKHETI", "name": "Samtskhe-Javakheti" }, { "id": 138, "iso": "GE", "code": "GURIA", "name": "Guria" }, { "id": 139, "iso": "GE", "code": "MTSKHETA_MTIANETI", "name": "Mtskheta-Mtianeti" }, { "id": 140, "iso": "GE", "code": "RACHA_LECHKHUMI_KVEMO_SVANETI", "name": "Racha-Lechkhumi and Kvemo Svaneti" } ], "meta": { "pageSize": 0, "page": 0, "total": "140" } } ``` --- # 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://docs.delos.financial/geo/states-list.md?ask= ``` 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.