Hashed data refers to information that has undergone a one-way cryptographic transformation. It produces a fixed-length string (the hash) from any input data. Importantly, it is computationally infeasible to reverse-engineer the original data from the hash.
The Versium REACH APIs support hashed data inputs. Below is a description of the type of hashed data supported and best practices for customers that whish to use this type of data.
Supported Hashing Methods
The Versium REACH APIs currently support the following Hashing methods:
- MD5 (UPPER, lower, NaturalCase)
- SHA1 (UPPER, lower, NaturalCase)
- SHA256 (UPPER, lower, NaturalCase)
Input Fields that support Hashing Methods
Versium REACH APIs supports and accepts ONLY the following fields as hashed inputs:
- First Name
- Last Name
- Address
- City
- State
- Postal Code
- Business Name
- Phone Number - Note: phone number should have all non-numerics removed ("I.e. '123-456-7890' or '(123) 456-7890' should be converted to '1234567890' before hashing for best results)
- Email Address - natural case is not well supported for email address.
How to submit Hashed Input Data
To use this feature, simply hash the fields noted above and use it in the API query as one normally would. The Versium REACH APIs will take care of the rest.
Example of a Contact Append API where a SHA256 phone number is given as input:
https://api.versium.com/v2/contact?output[]=email&output[]=address&phone=3c95277da5fd0da6a1a44ee3fdf56d20af6c6d242695a40e18e6e90dc3c5872c
Best Practices
When working with Versium REACH APIs, following these steps for hashing data ensures consistency and accuracy:
Remove Leading and Trailing Whitespace:
Before hashing, trim any extra spaces at the beginning or end of the data. This step ensures uniformity and avoids unintended variations.
Remove Non-Alphanumeric Characters (Except Spaces):
Cleanse the data by removing any characters that are not letters, digits, or spaces. Retain spaces, as they are often significant (e.g., in names or addresses).
Transform Uppercase Letters to Lowercase:
Convert all uppercase letters to lowercase. This normalization step ensures that case differences don’t affect the hash.
Hash the Field:
Finally, apply a secure cryptographic hash function (such as SHA-256) to the cleaned data. The resulting hash can be safely used in your API requests.
Remember, following these best practices ensures consistent and reliable results when using hashed data with Versium REACH APIs.
API call with fields hashed differently (mixed hashed input data)
Versium REACH APIs offer flexibility by accepting various hash types within the same API call. For instance:
- You can provide the First Name in SHA256 format.
- The Last Name can be hashed using SHA1.
- And the Email can be represented in MD5.
This versatility allows you to work with different hash algorithms based on your specific requirements.