# Verify addresses An HTTP POST is issued with the "ContentType" header specifying the format of the request and the "Accept" header specifying the format of the response. Endpoint: POST /doGlobalAddress ## Request fields (application/json): - `CustomerID` (string, required) The [License Key](https://docs.melissa.com/melissa/license/license-information.html) issued by Melissa. - `Format` (string) Specify the desired format of the response (XML or JSON). - `Options` (string) [Options](https://docs.melissa.com/cloud-api/global-address-verification/global-address-verification-reference-guide.html#options) - Specify which options to use for the selected action. List of options in OptionName:Parameter format. Multiple options are delimited with a ,. For example: OptionName:Parameter,OptionName:Parameter. - CountryOfOrigin: - This is used to determine whether or not to include the country name as the last line in FormattedAddress. - DeliveryLines: - This options allows you to specify if the Address Lines 1-8 should contain just the delivery address or the entire address. Default of off has Address Lines 1-8 return the entire address. - DetailedResults: - This is for users that have experience or code using Address Object and would like to have those codes alongside the Global Address result codes. Default of OFF will not return extra result codes. - ExtendedDateTime: - Additional information related to time zone names and UTC information for both standard and daylight savings will be made available in the Extras section. Default of OFF will not provide additional output information. - GBExtras: - Allows you to choose to add the UPRN output. Default of OFF will not provide additional output information. - IncludeRemnant: - In cases where Global Address identifies a piece of the input as extra information, we label this as Remnant and can append it to the beginning of the address lines. Default of ON will append remnant (extra information) to the beginning of the address lines. - LineSeparator: - This is the line separator used for the FormattedAddress result. Default of SEMICOLON uses a semicolon (;). - MelissaCityKeys: - When this option is enabled, ID fields representing a unique combination of ZIP Code, City, County, State, and Country will be appended to the Extras section. Currently available for the US. Default of OFF will not provide additional output information. - OriginDateTime: - (BETA) A string DateTime value with UTC data to use in the calculation of the local date time. For example: OriginDateTime:2022-01-13 18:33:16 (UTC-8:00). - OutputGeo: - Allows you to specify if you want geocoding output in the response. Default of ON will return latitude and longitude when available. - OutputScript: - This is the script type used for all applicable fields. Default of NOCHANGE will return the same script that is sent in. - Suggestion: - (BETA) Available only for single-record requests and currently supports addresses in the US, CA, and GB. In cases where Global Address cannot fully verify an address, alternate suggestions may be returned in the Suggestions response field. Default of OFF will not provide alternate address suggestions. - USExtras: - These are additional US only output will that can be made available in the Extras section. These outputs are related to Census, County, and School information. Default of OFF will not provide additional output information. - USPreferredCityNames: Allows you to override the city name and return only the USPS preferred city name. Default of OFF will leave valid vanity city names as preferred by the USPS. - USStandardizationType: Allows you to specify the standardization of the address abbreviation. Default of Short will leave the US address in short abbreviated form as preferred by the USPS. - `Records` (array, required) - `Records.AddressLine1` (string, required) The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs. - `Records.AddressLine2` (string) The input field for the address. - `Records.AddressLine3` (string) The input field for the address. - `Records.AddressLine4` (string) The input field for the address. - `Records.AddressLine5` (string) The input field for the address. - `Records.AddressLine6` (string) The input field for the address. - `Records.AddressLine7` (string) The input field for the address. - `Records.AddressLine8` (string) The input field for the address. - `Records.AdministrativeArea` (string, required) State, Province. The most common geographic data element. - `Records.Country` (string, required) The country name, abbreviation, or code. - `Records.DependentLocality` (string) Urbanization. The smaller population center data element. This depends on the Locality element. In terms of US Addresses, this element applies only to Puerto Rican addresses. It is used to break ties when a ZIP Code is linked to multiple instances of the same address. - `Records.DoubleDependentLocality` (string) The smallest population center data element. This depends on the Locality and DependentLocality elements. - `Records.LastName` (string) US Only. For addresses missing a secondary like a suite or apartment, we can use the last name and append that information for residential addresses. - `Records.Locality` (string, required) City, Municipality. The most common population center data element. - `Records.Organization` (string) The organization name associated with the address record. - `Records.PostalCode` (string, required) ZIP, Postcode. The complete postal code for a particular delivery point. If all three elements are provided and the PostalCode is incorrect, it can be corrected from the data on the Locality and AdministrativeArea. - `Records.RecordID` (string) A unique identifier for the current record. Use this to match the record submitted with the record returned. - `Records.SubAdministrativeArea` (string) County. The smallest geographic data element. - `Records.SubNationalArea` (string) The administrative region within a country on an arbitrary level below that of the sovereign state. - `TransmissionReference` (string) This is a string value that serves as a unique identifier for this set of records. It is returned as sent. ## Response 200 fields (application/json): - `Version` (string) The current service version number. - `TransmissionReference` (string) Optional. Serves as a unique request identifier. - `TransmissionResults` (string) Lists error codes from any errors caused by the most recent request as a whole. For more information, see [Global Address Verification Result Codes](https://docs.melissa.com/cloud-api/global-address-verification/result-codes.html). - `TotalRecords` (string) Total number of records. - `Records` (array) - `Records.RecordID` (string) The number of the record. Always 1 for a single email request, otherwise it serves as an index of the array of records. - `Records.Results` (string) Comma delimited status, error codes, and change codes for the record. For more information, see [Global Address Verification Result Codes](https://docs.melissa.com/cloud-api/global-address-verification/result-codes.html). - `Records.FormattedAddress` (string) The address in the correct format for mailing from the country specified in the CountryOfOrigin element. This includes the Organization as the first line, one or more lines in the origin country’s format, and the destination country (if required). Separate lines will be delimited by what is specified in the LineSeparator option. - `Records.Organization` (string) Business, Company. String value that matches the Organization request element. It is not modified or populated by the service. - `Records.AddressLine1` (string) These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code. If the DeliveryLines option is turned on, only the address up to the dependent locality will be returned. - `Records.AddressLine2` (string) Standardized or corrected contents of the input address line 2. - `Records.AddressLine3` (string) Standardized or corrected contents of the input address line 3. - `Records.AddressLine4` (string) Standardized or corrected contents of the input address line 4. - `Records.AddressLine5` (string) Standardized or corrected contents of the input address line 5. - `Records.AddressLine6` (string) Standardized or corrected contents of the input address line 6. - `Records.AddressLine7` (string) Standardized or corrected contents of the input address line 7. - `Records.AddressLine8` (string) Standardized or corrected contents of the input address line 8. - `Records.SubPremises` (string) Suite, Apartment. The parsed SubPremises from the AddressLine elements. A subpremise are individual units with their own addresses inside a building. - `Records.DoubleDependentLocality` (string) The standardized contents of the DoubleDependentLocality element. A double dependent locality is a logical area unit that is smaller than a dependent locality but bigger than a thoroughfare. This field is very rarely used. Great Britain is an example of a country that uses double dependent locality. - `Records.DependentLocality` (string) Urbanization. The standardized contents of the DependentLocality element. A dependent locality is a logical area unit that is smaller than a locality but larger than a double dependent locality or thoroughfare. It can often be associated with a neighborhood or sector. Great Britain is an example of a country that uses double dependent locality. In the United States, this would correspond to Urbanization, which is used only in Puerto Rico. - `Records.Locality` (string) City. The standardized contents of the Locality element. This is the most common geographic area and used by virtually all countries. This is usually the value that is written on a mailing label and referred to by terms like City, Town, or Postal Town. - `Records.SubAdministrativeArea` (string) County. The standardized contents of the SubAdministrativeArea element. This is a logical area that that is smaller than the administrative area but larger than a locality. While many countries can have a sub-administrative area value, it is very rarely used as part of an official address. - `Records.AdministrativeArea` (string) State, Province. The standardized contents of the AdministrativeArea element. This is a common geographic area unit for larger countries. - `Records.PostalCode` (string) ZIP Code. The standardized contents of the PostalCode element. Most countries have some form of a postal code system. - `Records.PostalCodeType` (string) This is a country dependent field. This field returns an identifier that represents the type of postal code returned. Currently only the US uses this field. For a list of these codes, see the Product Codes list. - `Records.AddressType` (string) A one-character code for the type of address coded. - `Records.AddressKey` (string) This is a country dependent field: * US: This returns a 11 digit code representing the combination of the zip code, the plus4, and the delivery point. This is a fairly good representation of a unique US address and often used as the core of postal barcode. However, this code is not guaranteed to be unique to an individual address, please use the MelissaAddressKey instead for that purpose. It is possible that this field is empty or not 11 digits if the address is a Non-USPS address (link to something about non-usps addresses). * GB: This field returns the UDPRN, which stands for Unique Delivery Point Reference Number. It is an 8 character code that is assigned and maintained by Royal Mail to each delivery point address. * AU: This returns the DPID (Delivery Point ID). This is a 8 digit number that identifies a mailbox according to Australia Post. The AddressKey can be used by other Melissa services, such as Geocoder or RBDI. - `Records.SubNationalArea` (string) The standardized arbitrary administrative region below that of the sovereign state. A sub-national area is a logical area unit that is larger than an administrative area but smaller than the country itself. It is extremely rarely used. - `Records.CountryName` (string) The standardized contents of the CountryName element. - `Records.CountryISO3166_1_Alpha2` (string) The 2 letter ISO 3166 country code value. For example: US for United States or CA for Canada. - `Records.CountryISO3166_1_Alpha3` (string) The 3 letter ISO 3166 country code value. For example: USA for United States or CAN for Canada. - `Records.CountryISO3166_1_Numeric` (string) The ISO 3166 country number value. For example: 840 for United States or 124 for Canada. - `Records.CountrySubdivisionCode` (string) The ISO3166-2 code for country subdivisions, usually tied to the administrative area for a country. The format is the 2 letter country code followed by a dash followed by 2 or 3 characters or two numbers. For example: US-CA, CN-16, or AU-VIC. This field is only populated for the following countries: AE, AR, AT, AU, BB, BE, BH, BR,BS, CA, CH, CL, CN, CO, CR, DE, DK, DM, DO, ES, FI, FJ, FR, GB, GH, GT, GY, HN, ID, IE, IL, IN, IS, IT, JP, KR, KW, LT, LU, LV, MX, MY, NC, NG, NI, NL, NO, NZ, PE, PH, PK, PL, PR, PT, RS, SA, SG, SI, SV, TH, TR, UA, US, UY, VN. - `Records.Thoroughfare` (string) Street. The most common street or block data element. This value is a part of the address lines and contains all the sub-elements of the thoroughfare like trailing type, thoroughfare name, pre direction, post direction, etc. - `Records.ThoroughfarePreDirection` (string) Street PreDirection. The parsed prefix directional within the Thoroughfare field. - `Records.ThoroughfareLeadingType` (string) The parsed leading thoroughfare type indicator within the Thoroughfare field. A leading type is a thoroughfare type that is placed before the thoroughfare. For example, the thoroughfare type of Rue in Canada and France is placed before the thoroughfare, making it a leading type. - `Records.ThoroughfareName` (string) Street Name. The parsed name indicator within the Thoroughfare field. - `Records.ThoroughfareTrailingType` (string) Street Suffix. The parsed trailing thoroughfare type indicator within the Thoroughfare field. A trailing type is a thoroughfare type that is placed after the thoroughfare. For example, the thoroughfare type of Avenue in the US is placed after the thoroughfare, making it a trailing type. - `Records.ThoroughfarePostDirection` (string) Post Direction. The parsed postfix directional within the Thoroughfare field. - `Records.DependentThoroughfare` (string) Dependent Street. The parsed block data element. The dependent thoroughfare is a second thoroughfare that is required to narrow down the final address. This is rarely used. - `Records.DependentThoroughfarePreDirection` (string) The parsed prefix directional within the DependentThoroughfare field. - `Records.DependentThoroughfareLeadingType` (string) The parsed leading thoroughfare type indicator within the DependentThoroughfare field. - `Records.DependentThoroughfareName` (string) The parsed name indicator within the DependentThoroughfare field. - `Records.DependentThoroughfareTrailingType` (string) The parsed trailing thoroughfare type indicator within the DependentThoroughfare field. - `Records.DependentThoroughfarePostDirection` (string) The parsed postfix directional indicator within the DependentThoroughfare field. - `Records.Building` (string) The parsed descriptive name identifying an individual location. - `Records.PremisesType` (string) The parsed leading premise type indicator within the premises field. - `Records.PremisesNumber` (string) House Number. The parsed alphanumeric indicator within the premises field. - `Records.SubPremisesType` (string) Suite Name. The parsed sub premises type indicator within the premises field. - `Records.SubPremisesNumber` (string) Suite Number. The parsed sub premises number indicator within the premises field. - `Records.PostBox` (string) The parsed post box information for a particular delivery point. - `Records.Latitude` (string) The parsed geographic coordinate for a particular delivery point. - `Records.Longitude` (string) The parsed geographic coordinate for a particular delivery point. - `Records.DeliveryIndicator` (string) A one character code that indicates if the address is a residence (R), business (B), or unknown (U). It is not available for all countries. Currently, this field is available for the US, GB, NL and IE with more countries planned in the future. See Product Codes for a list of these codes. - `Records.MelissaAddressKey` (string) This is a globally unique and persistent key for the postal address, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary unique identifier for that address. With AddressKey (US and Canada only), if an address zip code changes, the AddressKey would also change. Melissa Address Key (MAK) is independent and will not change. This makes MAK a good way to permanently identify and also to use as a value for finding duplicates. Currently, we return MAK numbers for over 50 countries with more planned for the future. - `Records.MelissaAddressKeyBase` (string) Every full address has its own Melissa Address Key (MAK). If that address is a suites or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. This provides a link between all the individual MAK addresses that belong to the same building. This field also returns a 10-digit proprietary key. Note, if we can validate the address to the building but not the suite, we can return just the BaseMAK. Currently available for countries that have support for MelissaAddressKey. - `Records.PostOfficeLocation` (string) The location of the post office in relation to the record address, if available. This may or may not be used in the official mailing address for the country in question. Currently, these are the countries we will return the data for: Serbia and Slovakia. - `Records.SubPremiseLevel` (string) A secondary piece of sub premise information used to describe a more generic division of the subpremise. For example, if you have an address like 1123 Market Way, Floor 12 Apt 25A then the Subpremises will be Apt 25A and the SubPremiseLevel will be Floor 12. This value is not widely used in official address data. SubPremiseLevelType and SubPremiseLevelNumber make up the SubPremiseLevel. - `Records.SubPremiseLevelType` (string) Floor. Part of the SubPremiseLevel. - `Records.SubPremiseLevelNumber` (string) Floor Number. Part of the SubPremiseLevel. - `Records.SubBuilding` (string) A smaller division of the building. For example, if an address has a building name that is a part of a larger set of buildings, then the sub building may be populated. SubBuildingType and SubBuildingNumber make up the parts of SubBuilding. - `Records.SubBuildingType` (string) This is part of the SubBuilding. - `Records.SubBuildingNumber` (string) This is part of the SubBuilding. - `Records.UTC` (string) The Coordinated Universal Time number in format of UTC+#. Note that there are timezones that are not whole hours only, like UTC+9:30. - `Records.DST` (string) Y or N, based on if the country or area of the input observes daylight savings time. Note that the value returned by the UTC output does not change based on whether the country/area is currently in daylight savings time for not. We will only return the standard timezone and this flag to indicate is daylight savings is observed. - `Records.DeliveryPointSuffix` (string) This is a country dependent field. This field returns an identifier that represents a suffix code usually tied to a delivery point. GB: This is a 2 character (first is numerical, 2nd character is alphabetic) that is assigned by Royal Mail. When added to the postal code, this allows each live delivery point to be uniquely identified. - `Records.CensusKey` (string) This is a country dependent field. It is designed to return a code that correspond to the census division information for a country. Currently, this field is only returned for the US. US: The CensusKey for the US is a 15 or 16 digit code that is made up of the following components: FIPS Code, Census Tract, Census Block, and CensusBlockGroup if it exists. - `Records.Extras` (object) The Extras section is a place where we will put less used output fields our more granular country specific output fields. This section is structured differently so that we have the flexibility to expand them in the future. These outputs structured as key/value pairs and the output values present in this section will depend on the options you have selected. You can find more details about the output format [here](https://docs.melissa.com/cloud-api/global-address-verification/global-address-verification-reference-guide.html#extras). ## Response 400 fields (application/json): - `type` (string) The type of error that occurred. - `title` (string) A short summary of the error. - `status` (string) The HTTP status code for the error. - `errors` (object) - `errors.$.` (array) A detailed message about the error. - `traceId` (string) A unique identifier for the request, useful for debugging.