{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-resources/ingrid-api/guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"United States (US)","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"united-states-us","__idx":0},"children":["United States (US)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["US addresses require a state (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["administrativeArea"]},") in addition to the standard"," ","fields. The house number comes before the street name, and postal codes (ZIP"," ","codes) are 5 digits with an optional 4-digit extension."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":1},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"countryCode\": \"US\",\n  \"postalCode\": \"94105\",\n  \"addressLines\": [\"123 Market Street\", \"Suite 400\"],\n  \"locality\": \"San Francisco\",\n  \"administrativeArea\": \"CA\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"field-requirements","__idx":2},"children":["Field requirements"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"US\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5-digit ZIP code (optionally with +4 extension)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLines"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (for shipment)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Index 0: number, street name, and type"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locality"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (for shipment)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["City"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["administrativeArea"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2-letter state abbreviation (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"CA\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"NY\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"TX\""]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subLocality"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Neighborhood — rarely needed"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"postal-code","__idx":3},"children":["Postal code"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Format:"]}," 5 digits, optionally followed by a dash and 4 more digits"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Regex:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["^\\d{5}(-\\d{4})?$"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Examples:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"94105\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"94105-1234\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sanitization:"]}," The API strips all characters except digits and dashes"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The 4-digit ZIP+4 extension improves delivery precision but is not required."," ","Most checkouts collect only the 5-digit ZIP code."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"administrative-area-state","__idx":4},"children":["Administrative area (state)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["administrativeArea"]}," field is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," for the United States. It must be"," ","a valid 2-letter USPS state abbreviation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All 50 states, the District of Columbia, and US territories are supported:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["States:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AZ"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GA"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ME"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MI"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NV"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NJ"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NM"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ND"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VA"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WV"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WY"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Federal district:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DC"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Territories:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GU"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FM"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PW"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VI"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Military:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AP"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["address form endpoint"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["administrativeArea"]}," as"," ","a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["select"]}," field type with all valid options pre-populated."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"address-lines","__idx":5},"children":["Address lines"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The house number comes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," the street name, followed by the street type."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"addressLines value"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLines"]}," value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standard"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"123 Market Street\"]"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["With suite"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"123 Market Street\", \"Suite 400\"]"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["With apartment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"456 Oak Avenue\", \"Apt 2B\"]"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PO Box"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"PO Box 1234\"]"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apartment, suite, unit, and floor numbers go on the second address line"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Street types (Street, Avenue, Boulevard, etc.) are part of the first line"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"locality","__idx":6},"children":["Locality"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locality"]}," field is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["city"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"San Francisco\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"New York\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Austin\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The city can be pre-filled from the ZIP code using the"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["address form endpoint"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes","__idx":7},"children":["Common mistakes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Mistake"},"children":["Mistake"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Problem"},"children":["Problem"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["administrativeArea"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for US addresses"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Include the 2-letter state code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"administrativeArea\": \"California\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full state name instead of abbreviation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the abbreviation: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"CA\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"addressLines\": [\"Market Street 123\"]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Street before number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["US uses number-first: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"123 Market Street\"]"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"postalCode\": \"94,105\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Comma in ZIP code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API strips non-digit characters automatically"]}]}]}]}]}]},"headings":[{"value":"United States (US)","id":"united-states-us","depth":1},{"value":"Example","id":"example","depth":2},{"value":"Field requirements","id":"field-requirements","depth":2},{"value":"Postal code","id":"postal-code","depth":2},{"value":"Administrative area (state)","id":"administrative-area-state","depth":2},{"value":"Address lines","id":"address-lines","depth":2},{"value":"Locality","id":"locality","depth":2},{"value":"Common mistakes","id":"common-mistakes","depth":2}],"frontmatter":{"title":"United States (US)","description":"Address requirements, postal code format, and field rules for the United States","seo":{"title":"United States (US)"}},"lastModified":"2026-02-24T19:14:57.409Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-resources/ingrid-api/guides/country-reference/united-states","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}