Get Acceptable Cities

Returns all cities that are mapped to a specified ZIP code and are eligible for merchant onboarding within the Netevia platform. This is useful for populating city dropdown options during merchant registration and ensuring that the city entered by the user is geographically valid for the given ZIP code.

Endpoint

GET /api/v1/merchant/acceptableCities

Authentication

Basic HTTP Authentication required.
Encode username:password in Base64 and pass in the Authorization header:

Authorization: Basic {base64(username:password)}

When to use

Call this endpoint when building a merchant onboarding form to dynamically populate the city dropdown after a user enters their ZIP code. Because a single ZIP code can span multiple cities (especially in metro areas), showing the user only the valid options reduces address data errors downstream. Use in conjunction with GET /api/v1/merchant/cityByZip which returns a single primary city, while this endpoint returns all eligible cities.

Query Parameters

Response

200 OK

{
  "data": [
    {
      "city": "AVENTURA",
      "state": "FL",
      "stateCode": 10
    },
    {
      "city": "GOLDEN BEACH",
      "state": "FL",
      "stateCode": 10
    },
    {
      "city": "MIAMI",
      "state": "FL",
      "stateCode": 10
    },
    {
      "city": "N MIAMI BEACH",
      "state": "FL",
      "stateCode": 10
    },
    {
      "city": "SUNNY ISLES BEACH",
      "state": "FL",
      "stateCode": 10
    }
  ],
  "requestId": 91203,
  "success": true,
  "error": null,
  "validationErrors": []
}

Error Codes

Common Mistakes

• Passing a ZIP code with a leading zero truncated (e.g., 1234 instead of 01234) — always send ZIP codes as strings with their full 5-digit representation.
• Expecting a single city result — this endpoint returns an array; some ZIP codes map to many cities.
• Using the returned city string directly as-is in form submissions — be aware values are uppercase; your application may need to normalize casing for display.
• Confusing this endpoint with cityByZip — acceptableCities returns all valid cities for a ZIP, while cityByZip returns only the primary city.

Related Endpoints

• GET /api/v1/merchant/cityByZip — returns the single primary city for a given ZIP code
• GET /api/v1/agentProfiles — retrieve agent profiles needed to create a merchant
• POST /api/v1/merchant/create — create the merchant application after validating location data

Example

curl -X GET "https://hq.staging.netevia.dev/api/v1/merchant/acceptableCities?zip=33160" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"