Help

Widget Api

List of EventsAnchor

All events emitted from the widget are prefixed with the nb: namespace and contain additional dtails in the details object of the event’s argument.

Event Dispatched from Included details Description
nb:registered Field Registration Id Fired on the field when registration occurs as long as the autoHookup configuration is enabled or if the registration argument for registerField is true. Used to register the feedback events on automatically registration.
nb:result Field Registration Id
Result Object
Error Message
Fired on the field when an API request is completed. See the result object for information pertaining to accessing the result.
nb:soft-result Field Registration Id Fired on the field when the field’s input doesn’t look like an email (i.e. no @ or .com/.net/etc…). Useful to prompt the user for a properly formatted email.
nb:clear Field Registration Id Fired from the form when the field’s input is being manipulated. Useful to hide feedback while the user is typing into the field.
nb:loading Field Registration Id Fired on the field when the API request starts. Can be used to display a loading indicator to the user.
nb:submit Form Registration Id, Result Object, Error Message Fired on the form when ajaxMode is enabled. This event is to be used for submitting ajax style forms. It’s important to use this event to process the sending of your form rather than the native submit event.

Event details objectsAnchor

Registration Id

This is a unique string used to identify the current field and form that the event was fired from. The id can be used to get the DOM node for the field or form.

field.addEventListener('nb:loading', function(e) {
    // Get the ID for this field
    var id = e.details.id;
    
    // Get the field
    var field = document.querySelector('#nb-field-' + id);
    
    // Get the form
    var form = document.querySelector('form[data-nb-form="' + id + '"]');
});

Result Object

The result object will contain the verification result from the API. It contains several methods which can be used to compare the result.

field.addEventListener('nb:result', function(e) {
    // Get result object
    var result = e.details.result;
    
    // Returns a string representing the result (valid, invalid, disposable, catchall, unknown)
    result.getResult();
    
    // Returns the numeric representation of the result (0,1,2,3,4)
    result.getNumericCode();
    
    // Returns true/false if an API error occured (i.e. low credit balance, invalid key, invalid referrer or throttled; specific error will be noted in the development concole)
    result.isError();
    
    // Returns true/false if the result is equal to the arguments. Can use numeric or string values and accepts several result codes in an array
    result.is('valid'); // Returns true is result is valid
    result.is(0); // Returns true if result is valid
    result.is(['valid','catchall']); // Returns true if result is valid or catchall
    result.is([0,3]); // Returns true if result is valid or catchall
    
    // Returns true/false if the result is not equal to the arguments. Can use numeric or string values and accepts several result codes in an array
    result.not('invalid'); // Returns true if result is not an invalid
    result.not(1); // Returns true if result is not an invalid
    result.not(['invalid','disposable']); // Returns true if result is not an invalid or disposable
    result.not([1,2]); // Returns true if result is not an invalid or disposable
});

Error Message

This is a readable error message returned by the server or by the client in the event of the timeout. These errors will also be logged in the browser’s development console.

field.addEventListener('nb:result', function(e) {
    // Get error message
    var error = e.details.error;
});

Below you will see the common error messages and our recommendations for each error:

Timeout

Timeouts will occur from time to time due to the nature of real-time verification. These are only an issue if they occur frequently or with larger email providers such as Gmail, Yahoo and the like. You can adjust the timeout with the timeout setting if this is happening too frequently or if the default timeout is too long.

Insufficient Credits

This will occur when you no longer have credits in your account. You can purchase additional credits within the dashboard or switch to monthly billing to avoid the issue altogether.

Bad Referrer

A bad referrer means the domain in which the widget is being used on is not authorized to use it. This is controlled from the “Trusted Domains” section within the widgets settings through the dashboard.

Throttling

Throttling is a protection method to curb and prevent abuse of your forms. This can be adjusted in the “Throttling” section of the widgets settings within the dashboard.