{
  "openapi": "3.1.2",
  "info": {
    "version": "",
    "title": "Melissa Keys Lookup",
    "x-seo": {
      "description": "Melissa Keys Lookup API. Retrieve Melissa address keys and identifiers for data matching and deduplication."
    },
    "description": "## Melissa Keys Lookup Overview ##\nThe Melissa Keys Lookup Cloud API allows you to search for the equivalent addresses associated with Melissa Address Keys (MAKs), which are unique identifiers generated by our address verification APIs.\n\nMelissa Keys Lookup can be used to:\n- Perform a reverse lookup against a MAK number to retrieve the equivalent address.\n- Index unique addresses across all countries using MAK numbers.\n- Resolve keys generated by services such as Global Address Web Service, Personator, and Smart Mover.\n\n**Documentation**\n- [Melissa Keys Lookup Documentation](https://docs.melissa.com/cloud-api/melissa-keys-lookup/melissa-keys-lookup-index.html)\n\n**Useful Resources**\n- [GitHub - Melissa Keys Lookup Open API Specification](https://github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specification/blob/main/openapi/apis/melissa-keys-lookup.yaml)\n- [Release notes](https://releasenotes.melissa.com/cloud-api/melissa-keys-lookup/)\n- [Result codes](https://docs.melissa.com/cloud-api/melissa-keys-lookup/result-codes.html)\n\n**Support Center**\n\n[https://www.melissa.com/company/product-support](https://www.melissa.com/company/product-support)\n"
  },
  "security": [],
  "tags": [
    {
      "name": "Melissa Keys Lookup",
      "description": "Use Melissa Keys Lookup endpoint to search for the equivalent addresses for Melissa Address Keys (MAKs)."
    }
  ],
  "servers": [
    {
      "url": "https://melissakeys.melissadata.net/V4",
      "description": "Melissa Keys Lookup Server"
    }
  ],
  "paths": {
    "/doMAKLookup": {
      "get": {
        "tags": [
          "Melissa Keys Lookup"
        ],
        "summary": "Lookup a Melissa Address Key (MAK)",
        "description": "Search for the equivalent address associated with a MAK.",
        "operationId": "doMAKLookupGET",
        "parameters": [
          {
            "$ref": "#/components/parameters/HeaderAcceptParam"
          },
          {
            "$ref": "#/components/parameters/HeaderContentTypeParam"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "The [License Key](https://docs.melissa.com/melissa/license/license-information.html) issued by Melissa. This only takes a license key, it will not accept the Customer ID.\n",
            "schema": {
              "type": "string",
              "format": "password"
            },
            "example": "{REPLACE-WITH-YOUR-LICENSE-KEY}"
          },
          {
            "name": "format",
            "in": "query",
            "description": "The output format.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "JSON",
                "XML"
              ],
              "default": "XML"
            },
            "example": "JSON"
          },
          {
            "name": "opt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "[Options](https://docs.melissa.com/cloud-api/melissa-keys-lookup/melissa-keys-lookup-reference-guide.html#options) - List options in the format `OptionName:Parameter`, with multiple options delimited with a `,`.\n\nFor example: `OptionName:Parameter,OptionName:Parameter`\n- `ResponseSchema:< Global | US >` - Converts the output fields to use naming conventions for the specified country. Default is `US`\n"
          },
          {
            "name": "ctry",
            "in": "query",
            "required": false,
            "description": "The country where your MAK lookup is for. This helps optimize MAK searches.",
            "schema": {
              "type": "string"
            },
            "example": "US"
          },
          {
            "name": "mak",
            "in": "query",
            "required": true,
            "description": "The MAK number input (US and Global). MAK Numbers are unique identifiers for all delivery point addresses for all countries when available.",
            "schema": {
              "type": "string"
            },
            "example": "8008006245"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Response"
                },
                "example": {
                  "Version": "9.4.0.1055",
                  "TransmissionReference": "Test",
                  "TransmissionResults": "",
                  "TotalRecords": "1",
                  "Records": [
                    {
                      "RecordID": "1",
                      "Results": "MK01",
                      "AddressLine1": "3 Chemin de la Barrière",
                      "AddressLine2": "22650 Beaussais-sur-Mer",
                      "City": "Beaussais-sur-Mer",
                      "State": "Côtes-d'Armor",
                      "PostalCode": "22650",
                      "CountryName": "France",
                      "CountryISO3166_1_Alpha2": "FR",
                      "CountryISO3166_1_Alpha3": "FRA",
                      "CountryISO3166_1_Numeric": "250"
                    },
                    {
                      "RecordID": "1",
                      "Results": "MK01",
                      "AddressLine1": "22382 Avenida Empresa",
                      "AddressLine2": "",
                      "City": "Rancho Santa Margarita",
                      "State": "CA",
                      "PostalCode": "92688-2112",
                      "CountryName": "United States",
                      "CountryISO3166_1_Alpha2": "US",
                      "CountryISO3166_1_Alpha3": "USA",
                      "CountryISO3166_1_Numeric": "840"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "HeaderAcceptParam": {
        "in": "header",
        "name": "Accept",
        "description": "Format of the response.",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "application/json",
            "*/*"
          ]
        },
        "example": "application/json"
      },
      "HeaderContentTypeParam": {
        "in": "header",
        "name": "Content-Type",
        "description": "Format of the request.",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "application/json",
            "application/xml"
          ]
        }
      }
    },
    "schemas": {
      "Response": {
        "type": "object",
        "properties": {
          "TotalRecords": {
            "type": "string",
            "description": "Total number of records."
          },
          "TransmissionReference": {
            "type": "string",
            "description": "*Optional*. Serves as a unique request identifier.\n"
          },
          "TransmissionResults": {
            "type": "string",
            "description": "Lists error codes from any errors caused by the most recent request as a whole. For more information, see [Melissa Keys Lookup Result Codes](https://docs.melissa.com/cloud-api/melissa-keys-lookup/result-codes.html)."
          },
          "Version": {
            "type": "string",
            "description": "The current service version number."
          },
          "Records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseRecord"
            }
          }
        }
      },
      "ResponseRecord": {
        "type": "object",
        "properties": {
          "AddressLine1": {
            "type": "string",
            "description": "These are string values that return the standardized or corrected address for the associated MAK."
          },
          "AddressLine2": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 2."
          },
          "AddressLine3": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 3."
          },
          "AddressLine4": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 4."
          },
          "AddressLine5": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 5."
          },
          "AddressLine6": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 6."
          },
          "AddressLine7": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 7."
          },
          "AddressLine8": {
            "type": "string",
            "description": "Standardized or corrected contents of the input address line 8."
          },
          "AdministrativeArea": {
            "type": "string",
            "description": "State, Province. This is a common geographic area unit for larger countries."
          },
          "City": {
            "type": "string",
            "description": "The city name for the associated MAK."
          },
          "CountryISO3166_1_Alpha2": {
            "type": "string",
            "description": "The 2 letter ISO 3166 country code value.\n\nFor example: `US` for United States or `CA` for Canada.\n"
          },
          "CountryISO3166_1_Alpha3": {
            "type": "string",
            "description": "The 3 letter ISO 3166 country code value.\n\nFor example: `USA` for United States or `CAN` for Canada.\n"
          },
          "CountryISO3166_1_Numeric": {
            "type": "string",
            "description": "The ISO 3166 country number value.\n\nFor example: `840` for United States or `124` for Canada.\n"
          },
          "CountryName": {
            "type": "string",
            "description": "The full country name for the associated MAK."
          },
          "CountrySubdivisionCode": {
            "type": "string",
            "description": "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.\n\nFor example: `US-CA`, `CN-16`, or `AU-VIC`.\n\nThis 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.\n"
          },
          "DependentLocality": {
            "type": "string",
            "description": "Urbanization. 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.\n\nGreat 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.\n"
          },
          "DoubleDependentLocality": {
            "type": "string",
            "description": "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.\n\nGreat Britain is an example of a country that uses double dependent locality.\n"
          },
          "Locality": {
            "type": "string",
            "description": "City. 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."
          },
          "PostalCode": {
            "type": "string",
            "description": "ZIP Code. Most countries have some form of a postal code system."
          },
          "RecordID": {
            "type": "string",
            "description": "The number of the record. Always `1` for a single request, otherwise it serves as an index of the array of records."
          },
          "Results": {
            "type": "string",
            "description": "Comma delimited status, error codes, and change codes for the record."
          },
          "State": {
            "type": "string",
            "description": "The state name."
          },
          "SubAdministrativeArea": {
            "type": "string",
            "description": "County. 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."
          },
          "SubNationalArea": {
            "type": "string",
            "description": "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."
          },
          "SubPremises": {
            "type": "string",
            "description": "Suite, Apartment. A subpremise are individual units with their own addresses inside a building."
          }
        }
      }
    },
    "responses": {
      "ErrorResponse": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "The type of error that occurred."
                },
                "title": {
                  "type": "string",
                  "description": "A short summary of the error."
                },
                "status": {
                  "type": "integer",
                  "description": "The HTTP status code for the error."
                },
                "errors": {
                  "type": "object",
                  "properties": {
                    "$.<PropertyName>": {
                      "type": "array",
                      "description": "A detailed message about the error.",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "traceId": {
                  "type": "string",
                  "description": "A unique identifier for the request, useful for debugging."
                }
              }
            }
          }
        }
      }
    }
  }
}