Best Practices: Real-time Single Transaction API

The Real-Time Single Transaction API is a simple JSON-based REST Web Service that allows you to verify email addresses, phone numbers, and U.S. and Canadian mailing addresses on demand as a user enters them in a web form or mobile application.

Below are some recommended best practices for you and your development team to consider when  implementing:

Do

• Check out the documentation
  It's worth looking through our documentation before you start. There you can find examples of method calls and responses to guide implementation.
  
  
• Implement safeguards
  Having the ability to conveniently verify emails in real time is a valuable thing. Because of this, bad actors may want to take advantage of your implementation for their own purposes. Failure to plan for this can lead to unexpectedly high use of your credits and even worse: your form(s) getting bogged down with malevolent traffic and causing problems for legitimate customers. It's wise to plan for it by:
  
  
  • Keeping your API key(s) safe. You are responsible for verifications processed through your API key(s), so you should keep them safe. We strongly recommend using BriteVerify Public Keys to achieve this goal.

    How do I know if my API key is vulnerable?
    Here's a simple trick: go to the web page that has your form. Open up your browser's source code panel. Perform a text search using part of your API key. If you can see it in the code, then so can everyone else.

  • Consider general throttling. As a fallback to your API key safety measures (or if you can't do what's recommended above), try limiting the number of submissions your form will accept every second or every minute. This may require upfront analysis of your traffic flow to get it right. This way, if your key becomes compromised before you can replace it, the damage can be mitigated. If you do not have the engineering resources or time to do this, it can easily be achieved using Public Keys as well.
    
    
  • Consider IP-based restrictions. The next step after that would be to limit submissions based on the end user's IP address. For example, you might limit a given IP address to 5 or 10 submissions per hour, and if that limit is hit force the end user to verify a CAPTCHA, or block them outright. It depends on what makes the most sense for your users. Again, this type of restrictions is easily possible with Public Keys.
    
    
• Set your form to allow Accept All and Unknown statuses as well
  While these results do carry risk, most of our customers will allow those statuses to pass in order to minimize interruption to the user flow. Much of the risk associated with these addresses is due to age. Since this API collects the data in real time, it is less likely to be an old email address. Learn more about Accept All and Unknown statuses.
  
  
• Block Role and Disposable addresses
  Disposable email addresses are temporary. While they may be Valid at the time of verification, they will self-destruct and become invalid (for example, within 10 minutes after creation). Most email service providers automatically suppress these addresses outright. More information about role and disposable addresses can be found in our status key.
  
  

Don't

• Don't use this API for bulk verification
  This API is designed for performing verifications on the fly, one at a time. If you want to verify in batches, check out our Bulk API. 

Getting Started

1. Read through the documentation for the API that you want to use.
2. Review the best practice guidelines: 
   • Best practices for the Real-time Single Transaction API
   • Best practices for the Bulk Validation API
3. Create a BriteVerify account.
4. Create an API key in the API Keys tab, and make sure that it is active.
5. Get verifying!

We're here for you
If you or your developers have any specific questions or problems, please let us know and we'll be happy to help.