Basics for Melissa Cloud APIs

Basics for Melissa Cloud APIs#

Once you have a Melissa Cloud API License (Licensing), you can go ahead and start using it. Here are the basics of getting started:

Supported Protocols#

The main protocols that Melissa services support are JSON and XML. Your request may be sent to our service via:

REST#

REST uses HTTP GET to fully include all the information needed in the URL. With this method, you can send single record requests by combining the elements together into a single URL. You can put this URL in a web browser, a tool like Postman, or an application. You can specify in the REST request if you would like a JSON response or an XML response.

  • Full Request
  • Domain
  • Sub Directory/Path
  • Query

This is the full REST request. For details on individual parts of this request, use the tabs above.

https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify?format=json&id=66778150&act=Check&a1=22382+Avenida+Empresa&postal=92688

The domain indicates which web service to access.

https://personator.melissadata.net

The sub directory, or path, indicates exactly which endpoint to use for the API.

/v3/WEB/ContactVerify/doContactVerify

The query contains the request elements to the API.

?format=json&id=66778150&act=Check&a1=22382+Avenida+Empresa&postal=92688

Note

You may have to account for special escape characters when using REST: Escape Characters.

BATCH JSON/XML#

This protocol uses HTTP POST to submit a request. Using this method, you would send as the body a JSON or XML document. Inside this document can contain between 1 to 100 individual records.

  • JSON
  • XML
{
  "CustomerID": "string",
  "Options": "string",
  "Records": [
    {
      "Input1": "string",
      "Input2": "string",
        "...": "...",
        "...": "...",
      "Input10": "string"
    }
  ]
}

https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify?format=json&id=66778150&act=Check&a1=22382+Avenida+Empresa&postal=92688

Some services may also support JSONP and SOAP. For SOAP specifically, we encourage users to migrate away and use either XML or JSON. We have found that users generally get a speed bump moving from SOAP to JSON or XML.

Real-Time vs Batch#

Most Melissa Cloud API’s will support both Real-Time and Batch.

Real-Time#

Designed to process a single record at a time, usually with a live end-user where speed is a top priority. A common use case is a website where a user enters their address and that address is verified in real time. We recommend using the REST protocol in this situation.

Batch#

A Batch situation is where there is a list of records to process. In this situation, speed is usually not as critical as there is no live user waiting on the results. If there is a live user, most users recognize that batches take longer than single records.

In this situation, the Batch JSON or Batch XML protocol should be used. The batching application should break up the records into chunks of 100 records and send them as a HTTP POST JSON or XML request. Cycle through the full batch 100 records at a time. If speed is a concern, multiple simultaneous threads can be used, but keep in mind the rate limiting protections. These are listed on the Rate Limiting page: Rate Limiting.

Handling Errors#

After sending a Melissa Cloud API request, there are several layers of possible errors that can come back.

HTTP Level Error#

A top level error that may be returned will be a HTTP Response Status Code. The only HTTP Status Code that we will explicitly trigger on purpose is the HTTP 429 when rate limiting protection is activated. However, others are still possible due to client or server error.

429 Too Many Requests#

Please see our Rate Limiting page: Rate Limiting.

400 Bad Request#

This usually means that the JSON or XML request is not valid or does not contain data that the Cloud API expects. Another possibility is missing or bad data in the HTTP Header.

404 Not Found#

This means the expect website or web application was not found. This usually indicates an issue with the URL.

408 Request Timeout#

When this error is received, our service did not return a response in the time expected by the client code and the client terminated the connection. If this error occurs, we recommend retrying the request up to 3 times. Often, you will be able to get the response back quickly with a retry. For more info on retrying, please see our Retrying page: Retrying.

Service Level Error#

For major errors not related to the input data, Melissa uses a Service Level output called TransmissionResults. We use this to return errors or statuses tied to the full response, not to any individual input records.

../../_images/transimssion_results_ge05.png

TransmissionResults would be used to notify the user of errors related to their license, expected fields that are missing, asking for functionality not allowed, etc. Here is the list of transmission result codes: Service Level Result Codes.

Results Codes#

Melissa uses the concept that we call Results Codes. The main features of Results codes are:

  • They are two letters followed by two numbers (IE: AS01).

  • Multiple Results Codes can be returned together with delimiters (IE: AS02,AE10,AC01).

Let’s go to Results Codes University and take a quick class on the proper way to use Results Codes.

  1. Know Your Results Codes

    Melissa has a lot of products and ever more Results codes. Most of them are self-explanatory. In order to use Results properly, you need to know what is possible and what is not. Review the possible Results for the Cloud API you are working with. If there are any questions, contact Melissa support and we will be more than happy to guide you.

  2. Define Good

    The ultimate goal of the Result Codes is to allow you to make a decision. The most basic and most common decision is, “Is this record good or bad?” For most users, if the record is good, it will go into one bucket. Those records are good to mail, or good to store. It a record is not good, they will likely go into another bucket. Those records can then undergo additional intervention.

    What constitutes “good” for a user is in the eye of the beholder. Different companies have different use cases, so that is why Point #1 above is so important.

  3. Use Contains and Cascade Your Results

    With Results being a delimited list, you cannot simply do a direct comparison. You should use the equivalent of a Contains function to categorize your results.

    if(Results.Contains("AS01"))
  {
    //Perform actions for this Good record
  }

    This is a very simple case. However, you will often want to look for more than 1 result code.

    if(Results.Contains("AS01") or Result.Contains("AS03"))
  {
    //Perform actions for this Good record
  }

    After you have found your “good” record, by definition everything else will fall into “not good”.

    if(Results.Contains("AS01") or Result.Contains("AS03"))
  {
    //Perform actions for this Good record
  }
else
  {
    //Perform actions for this “not good” record
  }

    Once you get used to it, you can see that the possibilities are endless. Maybe you want more than 2 categories. The Result Codes allow just that.

    if(Results.Contains("AS01") or Result.Contains("AS03"))
  {
    //Perform actions for this Good record
  }
else if (Results.Contains("AS02"))
  {
    //Perform actions for this partially good record
  }
else
  {
    //Perform actions for this “not good” record
  }

  4. Stay Flexible

    There are quite a lot of result codes. And guess what? There will be more in the future. We are constantly looking to add new features and improve our products.

    With that said, we don’t know exactly what those changes will be. That’s why we used String.Contains() when detecting for codes. That way any reordering or future additions won’t affect your current code. It’s also good to have a catch all Else at the end of your result code decision tree. This way, no records can fall through the cracks.

Contents