Get City By ZIP

Looks up the primary city associated with a given US ZIP code and returns the city name, two-letter state abbreviation, and internal state code. This is used during merchant onboarding to auto-populate the city field when a user enters their ZIP code, reducing manual data entry errors.

Endpoint

GET /api/v1/merchant/cityByZip

Authentication

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

Authorization: Basic {base64(username:password)}

When to use

Use this endpoint to implement ZIP-to-city auto-fill on merchant onboarding forms. When the user enters a ZIP code, call this endpoint to populate the city field automatically. For ZIP codes that span multiple cities, use GET /api/v1/merchant/acceptableCities instead to present the user with all valid options. This endpoint returns only the single primary city for the ZIP code and is best suited for single-city ZIP codes or when only a default value is needed.

Query Parameters

Response

200 OK

{
  "data": {
    "city": "NORTH MIAMI BEACH",
    "state": "FL",
    "stateCode": 10
  },
  "requestId": 91901,
  "success": true,
  "error": null,
  "validationErrors": []
}

Error Codes

Common Mistakes

• Sending a 4-digit ZIP code with the leading zero stripped — always pass ZIP codes as 5-character strings (e.g., "07030" not "7030").
• Assuming the returned city exactly matches what users type — the city name is returned in uppercase; normalize casing in your UI if needed.
• Using this endpoint for ZIP codes that cover multiple cities without validating further — use GET /api/v1/merchant/acceptableCities to get the full list when needed.
• Ignoring the stateCode field — while state is the human-readable two-letter code, stateCode may be required by other Netevia API fields for address submissions.

Related Endpoints

• GET /api/v1/merchant/acceptableCities — returns all cities mapped to a ZIP code (use when a ZIP spans multiple cities)
• POST /api/v1/merchant/create — create the merchant application after validating address data
• POST /api/v2/merchant/create — v2 merchant create endpoint that accepts city/state/ZIP fields

Example

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