Keap’s API requires ISO 3166 country codes (Alpha-3 format) and hyphenated state/province codes (Alpha-2 + subdivision) to accept address data. Skip either requirement and the API returns REGION invalid or COUNTRY CODE errors that break every downstream automation dependent on that contact record.

Address formatting errors in Keap are silent killers for automation workflows. The API accepts the payload — no timeout, no HTTP 500 — but the contact record saves with a corrupted or blank region field. Sequences fire incorrectly, shipping integrations route to the wrong address, and personalization tags pull empty strings.

If you are building automations that push contact data into Keap via API — whether from a CRM sync, a Make scenario, or a custom HTTP module — these seven rules will stop address-related failures before they reach production. For broader context on how automation tools handle API data mapping, see the Make vs Zapier feature breakdown and the guide on feeding API docs into Claude to build HTTP modules.

Why Does Keap’s API Return Address Errors?

Keap validates address fields against the ISO 3166 standard on write. When the API receives a payload with a region value and no valid country code, or a region code that does not match the country’s Alpha-2 prefix, it returns one of two errors:

• “REGION is invalid” — the state or province code does not exist in Keap’s ISO 3166-2 lookup for the given country.
• “COUNTRY CODE needed if Region Exists” — a region was submitted without a corresponding country code, so Keap cannot validate the subdivision.

Both errors prevent the contact record from saving correctly. Automations built on top of that record — email sequences, tagging logic, shipping triggers — behave unpredictably or fail silently. Understanding the root cause before building is core to the OpsMap™ pre-automation checklist.

Rule 1: Use Alpha-3 Codes for the Country Field

Keap’s API country_code field requires the ISO 3166-1 Alpha-3 three-character code — not the two-character Alpha-2 code used in most other systems. This is the single most common source of address failures for developers migrating from other platforms.

Correct examples:

• United States → USA
• Canada → CAN
• United Kingdom → GBR
• Australia → AUS
• Germany → DEU

Submitting US instead of USA does not always return an explicit error — Keap saves the record with a blank or misidentified country. That silent failure is harder to catch than an outright rejection.

Rule 2: Format State and Province Codes With a Hyphen and Alpha-2 Prefix

The region field in Keap’s API follows the ISO 3166-2 standard: Alpha-2 country code + hyphen + subdivision abbreviation.

Correct examples:

• Indiana, United States → US-IN
• California, United States → US-CA
• British Columbia, Canada → CA-BC
• Ontario, Canada → CA-ON
• New South Wales, Australia → AU-NSW

Submitting IN or Indiana alone triggers the “REGION is invalid” error. The hyphen is not optional — Keap’s validation is exact-match against the ISO 3166-2 code list.

Rule 3: Never Submit a Region Without a Country Code

If your payload includes a region value, country_code must also be present in the same request. Keap uses the country code to look up valid subdivision codes. Without it, any region value — even a correctly formatted one — triggers the “COUNTRY CODE needed if Region Exists” error.

In Make, this means both fields must be mapped in the same HTTP module or Keap module. If country data is missing from your source record, add a fallback value or a conditional branch that strips the region field rather than sending it empty. The guide on building Make scenarios with Claude covers conditional field mapping in detail.

Rule 4: Match the Alpha-2 Prefix in the Region Code to the Country Being Submitted

The Alpha-2 prefix in your region value must match the country you are targeting — not the country stored in the Keap record, and not a hardcoded default from your integration. Submitting country_code: CAN with region: US-TX returns a “REGION is invalid” error because Texas is not a Canadian subdivision.

This mismatch appears most often in:

• Multi-country contact imports where region codes are copied from a US-formatted template
• Make scenarios that transform region data without updating the country prefix
• Third-party CRM syncs that normalize all states to US format before pushing to Keap

The fix is a lookup or transform step that derives the correct Alpha-2 prefix from the country value before constructing the region string. See the HTTP module build guide for examples of inline data transformation in Make.

Rule 5: Do Not Use ISO 3166-1 Alpha-2 Codes for the Country Field

Many APIs — including Salesforce, HubSpot, and most shipping platforms — accept the two-character Alpha-2 country code (US, CA, GB). Keap does not. Its country_code field requires Alpha-3.

When you submit an Alpha-2 code to Keap, the API does not always return an error. In some cases it saves the record with the wrong country or no country at all. This is particularly dangerous in automated workflows because the failure is invisible at the time of write — it surfaces later as bad data in reporting, broken personalization, or failed regional logic.

If your source system outputs Alpha-2, add a mapping step that converts to Alpha-3 before the Keap write. A static lookup table in a Make data store or a JSON module with a country map handles this reliably. The AI-assisted Make builds comparison shows when a lookup table approach outperforms inline formulas.

Rule 6: Validate Address Fields Before Writing to Keap

Pre-write validation catches format errors before they corrupt contact records. Build a validation step into your Make scenario that checks both fields against known-good values before the Keap write module executes.

A practical validation pattern:

• Maintain a data store with all valid ISO 3166-1 Alpha-3 country codes
• Maintain a second data store or JSON object with valid ISO 3166-2 subdivision codes keyed by country
• Before the Keap write, run a lookup on both values
• If either lookup fails, route the record to an error handler rather than writing corrupt data

This pattern is covered in the routed error handling guide for Make. Pre-write validation is also a core step in the OpsMap pre-automation checklist — knowing your data quality before you automate prevents a category of failures that are expensive to fix after the fact.

Rule 7: Update Legacy Records That Use Deprecated Subdivision Codes

ISO 3166-2 subdivision codes are not static. Countries periodically rename, merge, or reassign provincial and state codes. Keap validates against a current ISO 3166-2 list, so a region code that was valid two years ago triggers a “REGION is invalid” error today if that code has been deprecated.

This affects teams that:

• Migrated a legacy contact database into Keap without re-validating address fields
• Imported records from a system that cached ISO codes from an older specification
• Built API integrations several years ago and have not reviewed the address mapping since

The fix requires a one-time audit of existing region values against the current ISO 3166-2 list, followed by a batch update via the Keap API for any records carrying deprecated codes. For teams building that audit as a Make workflow, the Make scenario build walkthrough shows how to structure a batch read-transform-write pattern.

How These Rules Apply Inside Make Workflows

When Keap is a destination in a Make scenario, address field errors surface as module-level failures with the error text returned by the Keap API. Make’s error handling catches these — but only if you have configured a route for API-level errors, not just connection failures.

Best practices for Keap address handling in Make:

• Use a router before the Keap module to branch on whether both country_code and region are present and non-empty.
• Add a transformer module to convert Alpha-2 to Alpha-3 and construct the hyphenated region code from raw state/province data.
• Configure an error handler route on the Keap write module to catch validation errors and push failed records to a review queue rather than dropping them.
• Log failures to a data store or Google Sheet so address errors are visible and actionable without requiring someone to monitor scenario run history manually.

For a full walkthrough of error handler configuration, see setting up routed error handling in Make. For the broader question of when to validate inside the scenario versus upstream, the HRIS required fields vs manual data validation guide covers the tradeoffs in detail.

Additional Reading

• What Is a Make Scenario? The Plain-English Guide for Zapier Users
• How to Feed API Docs Into Claude to Build Make HTTP Modules Without Native Connectors
• How to Build a Make Scenario With Claude: A Step-by-Step Walkthrough
• How to Set Up Routed Error Handling in Make With AI Assistance
• 7 Questions to Ask Before You Automate Anything (The OpsMap Checklist)
• Make vs Zapier: A Straight Pricing and Feature Breakdown for 2026
• AI-Assisted Make Builds vs. Manual Builds (2026): Which Is Better for Your Automation?
• HRIS Required Fields vs Manual Data Validation: Which Is Safer for Small HR Teams?
• How to Evaluate a Make Scenario Built by AI Before It Goes to Production
• 7 Things an AI-Built Make Scenario Gets Wrong (And How to Catch Them)