Smarty

Market: US

This Data Core connector validates United States ZIP codes through the Smarty US ZIP Code API. It accepts a ZIP code with optional city and state filters, securely adds Smarty credentials from the Data Core configuration, and returns Smarty's location results without changing their structure.

Business Capabilities

Validate a US ZIP code and retrieve its associated cities, state, county, and geographic coordinates.
Narrow a ZIP lookup with an optional city and two-letter state code.
Keep Smarty authentication details inside Data Core configuration rather than exposing them to API consumers.
Return the upstream Smarty ZIP Code response as typed JSON.

Exposed Endpoints

The resource path exposed by the connector is /smarty/v1. Environments that publish Data Core APIs below /api make the full endpoint /api/smarty/v1/validate/zipcode.

Validate a ZIP code (POST /api/smarty/v1/validate/zipcode) — validates a US ZIP code and returns the matching city, state, county, and geographic details.

The endpoint consumes and returns application/json.

Vault Configuration

The connector reads configuration through Data Core ConfigService. Provision the following values through CMA/Vault or another approved secret source; never put real credentials in source control.

authId — Smarty authentication ID, sent as the auth-id query parameter.
authToken — Smarty authentication token, sent as the auth-token query parameter.
baseUrlZipCode — full Smarty US ZIP Code lookup URL.

For local development, create the ignored src/main/resources/connector-data.json file with values supplied by an approved secret source:

Copy

{
  "authId": "<smarty-auth-id>",
  "authToken": "<smarty-auth-token>",
  "baseUrlZipCode": "https://us-zipcode.api.smarty.com/lookup"
}

Request Structures and Samples

POST /api/smarty/v1/validate/zipcode

Validates a US ZIP code using the Smarty US ZIP Code API.

Field	Type	Required	Rules	Description
`zipcode`	string	Yes	Non-blank; maximum 10 characters	ZIP5 or ZIP9 value, with or without a hyphen.
`city`	string	No	Maximum 50 characters	City used to narrow the result.
`state`	string	No	Maximum 2 characters	Two-letter state abbreviation used to narrow the result.

Sample request:

Copy

{
  "zipcode": "90210",
  "city": "Beverly Hills",
  "state": "CA"
}

Copy

curl --request POST 'http://localhost:8080/api/smarty/v1/validate/zipcode' \
  --header 'Content-Type: application/json' \
  --data '{"zipcode":"90210","city":"Beverly Hills","state":"CA"}'

Sample response:

Copy

[
  {
    "input_index": 0,
    "city_states": [
      {
        "city": "Beverly Hills",
        "state_abbreviation": "CA",
        "state": "California",
        "mailable_city": true
      }
    ],
    "zipcodes": [
      {
        "zipcode": "90210",
        "zipcode_type": "S",
        "default_city": "Beverly Hills",
        "county_fips": "06037",
        "county_name": "Los Angeles",
        "state_abbreviation": "CA",
        "state": "California",
        "latitude": 34.08544,
        "longitude": -118.40445,
        "precision": "Zip5"
      }
    ]
  }
]

Response structure:

Field	Type	Description
`input_index`	integer	Index of the input submitted to Smarty.
`city_states`	array	Matching city and state combinations.
`city_states[].city`	string	City name.
`city_states[].state_abbreviation`	string	Two-letter state code.
`city_states[].state`	string	Full state name.
`city_states[].mailable_city`	boolean	Whether the city is mailable.
`zipcodes`	array	ZIP code details.
`zipcodes[].zipcode`	string	ZIP code returned by Smarty.
`zipcodes[].zipcode_type`	string	Smarty ZIP code type.
`zipcodes[].default_city`	string	Default city for the ZIP code.
`zipcodes[].county_fips`	string	County FIPS code.
`zipcodes[].county_name`	string	County name.
`zipcodes[].state_abbreviation`	string	Two-letter state code.
`zipcodes[].state`	string	Full state name.
`zipcodes[].latitude`	number	Latitude.
`zipcodes[].longitude`	number	Longitude.
`zipcodes[].precision`	string	Geographic precision returned by Smarty.

Integration Flow

The connector translates the JSON request into a GET request to the configured Smarty lookup URL. It appends auth-id, auth-token, zipcode, and, when supplied, city and state as URL-encoded query parameters. Smarty's JSON response is then returned to the caller.

Local Development

Prerequisites: Java 21 and Maven 3.9 or later.

Copy

mvn quarkus:dev

Useful local endpoints are:

Interface	URL
Swagger UI	`http://localhost:8080/api/internal/swagger-ui`
Health	`http://localhost:8080/api/internal/health`
Metrics	`http://localhost:8080/api/internal/metrics`

Run the integration tests with:

Copy

mvn test