Help

Getting Started With the API

Our verification API allows you to add email verification to any part of your software. We offer solutions for verifying individual emails as well as lists containing hundreds or even millions of emails.

To get started you will need to create an account and get your api username and api secret key from the API settings.

AuthenticationAnchor

Our API utilizes the popular OAuth 2.0 authentication model. This requires you to make an initial request for an access token before making verification requests. Below is an example of this initial request, just substitute your actual api username and api secret key.

curl -X POST -u <API USERNAME>:<API SECRET KEY> https://api.neverbounce.com/v3/access_token\
    -d grant_type=client_credentials\
    -d scope=basic+user

Note: In the above request the + is a urlencoded space. The scope is actually basic user
Note: If your api username or api secret key contain the $ character you may need to wrap the credentials in quotes for command line applications; ie: -u ‘<API USERNAME>:<API SECRET KEY>’

Response:

{
    "access_token":"4d277ec7686b1372af1cd8a428cc457553039db2",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"basic user"
}

Once you have your access token you can use it to verify emails or lists. This token will be valid for an hour and used for any number of requests. Once the access_token has expired, you’ll need to request a new one using the same request as above.

Error HandlingAnchor

From time to time you may experience an API error. It’s important to watch out for these and handle them appropriately.

Authentication Errors

When requesting an access_token is unsuccessful, you’ll receive a response containing an error and error_description parameter.

Example:

{
    "error": "invalid_request",
    "error_description": "The grant type was not specified in the request"
}

Codes:
invalid_client: The api username and/or api secret key is incorrect.
invalid_request: The request is missing a required parameter. Verify that you are passing the grant_type and scope parameters.
unsupported_grant_type: The grant type you’ve supplied is unsupported. Make sure you are passing in client_credentials as the grant type.
invalid_scope: The scope supplied is unsupported. Make sure you’ve supplied basic user as the scope.

Expired/Invalid Access Tokens

When an access_token expires or is invalid, you’ll receive the following response:

{
    "success": false,
    "msg": "Authentication failed"
}

API Errors

When an API request is unsuccessful, you’ll receive an error message containing a success parameter set to false. When this happens it will be accompanied by either a msg parameter or error_code and error_msg parameters together.

Example 1:

{
    "success": false,
    "error_code": 4,
    "error_msg": "You have reached your monthly free API usage limit. Please add a payment method in your account dashboard to continue using the API.",
    "execution_time": 0.13372898101807
}

Example 2:
{
    "success": false,
    "msg": "Missing required parameter 'email'"
}

A note on EncodingAnchor

When making requests to our API, you’ll want to make sure you always encode your data using x-www-form-urlencoded. This is especially important if you’re using a utility like Postman.