Skip to main content

Reference data — countries & subdivisions

Registration forms typically need a country/subdivision (state/province) dropdown. The Edge API exposes a read-only, non-tenant ISO-3166 catalog for exactly this — it needs only the touchpoint credential, no Customer JWT, since it's used before an account exists.

Fetching countries​

TP=(-H "X-Touchpoint-Code: <code>" -H "X-Touchpoint-Key: <key>")

curl -s "$BASE/api/v1/reference/countries" "${TP[@]}"
# → 200 [ { "code": "AR", "name": "Argentina" }, ... ]

Fetching subdivisions for a country​

curl -s "$BASE/api/v1/reference/countries/AR/subdivisions" "${TP[@]}"
# → 200 [ { "code": "AR-B", "name": "Buenos Aires" }, ... ]

An unknown country code returns 404 COUNTRY_NOT_FOUND.

Caching — this data barely ever changes​

Both endpoints return Cache-Control: public, max-age=86400 and a strong ETag. Cache the response and, on subsequent loads, send the cached ETag back as If-None-Match:

curl -s -D - "$BASE/api/v1/reference/countries" "${TP[@]}" | grep -i etag
# → ETag: "a1b2c3..."

curl -s -o /dev/null -w '%{http_code}\n' "$BASE/api/v1/reference/countries" "${TP[@]}" \
  -H 'If-None-Match: "a1b2c3..."'
# → 304  (no body — your cached copy is still current)

If you're building a web touchpoint, standard browser HTTP caching already does this for you automatically as long as you don't bypass the cache — no extra code needed. For a mobile app or backend integration, cache the response and its ETag yourself and send If-None-Match on refresh to avoid re-downloading the full list every time.