INTRODUCTION

Welcome to our Sales.Rocks API. The API is built to allow you quick and easy access to our services. The Sales.Rocks API is organized around REST and uses many standard HTTP features, like HTTP verbs, which can be understood by many HTTP clients.

JSON will be returned in all responses, including errors. The APIs are designed to have predictable, straightforward URLs and to use HTTP response codes to indicate API errors.

General principles

Services

You can enjoy our services with our simple Sales.Rocks API. The following services are available:

- The Email Verifier service returns info about deliverability of a given email.

- The Phone Verifier service returns info about a given phone number, such as as phone provider, country, etc.

Requests

Sample Request

POST https://api.sales.rocks/toolkit/emailVerifier

{
    "email": "randomstring@samplesolutions.eu"
}

All methods must be called using HTTPS. Data is passed as JSON data in a POST request. In order to do a proper JSON-formatted request, make sure you provide Content-Type: application/json in HTTP request headers.

Responses

Sample Response

{
    "email": "randomstring@sales.rocks",
    "top_level_domain": "Yes",
    "type": "Professional",
    "disposable": "No",
    "mx_records": [
        "ASPMX3.GOOGLEMAIL.COM.",
        "ASPMX2.GOOGLEMAIL.COM.",
        "ALT2.ASPMX.L.GOOGLE.COM.",
        "ASPMX.L.GOOGLE.COM.",
        "ALT1.ASPMX.L.GOOGLE.COM."
    ],
    "provider": "Google",
    "status": "Invalid",
    "format": "Ok",
    "full_inbox": "Not full",
    "message": "Domain does not have email service set up"
}

All data is sent and received as JSON. Each response sent from the API contains two types of responses - single object responses or collection of objects, depending on the service that you are using.

Errors

Error example:

{
  "error": 
    {
      "status_code": 400,
      "message": "Invalid request body"
    }
}

Sales.Rocks API use conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Stripe's servers (these are rare).

Status Codes

Common used status codes:

Status Code	Response	Description
200	OK	Everything worked as expected.
400	Bad Request	The client sends some invalid data in the request, for example, missing or incorrect content in the payload or parameters. Could also represent a generic client error.
401	Unauthorized	No valid API key provided, the client is not authorized to access the requested resource.
403	Forbidden	The API key doesn't have permissions to perform the request, the client is not authenticated.
404	Not Found	The requested resource doesn't exist.
429	Too Many Requests	The client is sending more than the allowed number of requests per unit time.
500	Server Error	Something went wrong on our end. (These are rare.)

Authentication

Intro

At Sales.Rocks, we use token-based authentication to allow our users limited access to our data. To get access to the protected resources using our APIs, OAuth 2 uses access tokens. An access token is a string representing the granted permissions. For more detailed information about OAuth 2 and token-based authentication, we recommend reading this article.

Before starting, you will need to sign up to https://app.sales.rocks/. The username and password used for creating your account will be needed later for getting the access token. If you already have account on our platform, you can skip this step.

Get access token

We are using JWT access tokens. JSON Web Token (JWT) access tokens conform to the JWT standard and contain information about an entity in the form of claims. They are self-contained therefore it is not necessary for the recipient to call a server to validate the token.

HTTP Request

curl --location --request POST 'https://api.sales.rocks/auth/accessToken' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "randomusername",
    "password": "randompassword"
}'

In order to get your access token, you need to send an HTTP POST request to the following endpoint:

Method	URL
POST	https://api.sales.rocks/auth/accessToken

Request parameters

As an input, you need to pass JSON formatted body with the your username and password as key/value parameters.

Body example:

{
  "username": "your_username_here",
  "password": "your_password_here"
} 

Key parameter	Value parameter
username	username that you use to log in on the platform.
password	password that you use to log in on the platform.

Response attributes

If you successfully followed all the steps, you will receive a JSON response containing the access token:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
} 

Attribute	Type	Description
access_token	string	The access token string as issued by the authorization server.
token_type	string	The type of token this is, typically just the string “Bearer”.
expires_in	string	The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.

Using the access token

These access tokens are also known as bearer tokens. You can use this token to call Sales.Rocks services, by adding it to the API request as an Authorization header.

Key	Value
Authorization	Bearer YOUR_ACCESS_TOKEN

Access tokens expire shortly (60 minutes) after they are issued for security reasons. If you need to communicate with our API beyond the access token's lifespan, you will need to request a new access token.

SERVICES

Email Verifier

Intro

Our Email Verifier API offers easy way to verify the deliverability of a given email. This API works on this principle - Domain level checks (top level domain, email type, disposable check, full inbox), followed by MX Record lookup for futher SMTP checks, thus completing the verification.

HTTP Request

curl --location --request POST 'https://api.sales.rocks/toolkit/emailVerifier' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "email": "randomstring@sales.rocks"
}'

Method	URL
POST	https://api.sales.rocks/toolkit/emailVerifier

Request parameters

Body example:

{
    "email": "randomstring@sales.rocks"
}

As an input, our API receives a JSON object with “emails” as key parameter and a list of emails that you want to verify, as value parameter.

Key parameter	Value parameter
email	Email to be verified

Response attributes

Response example:

{
    "email": "randomstring@sales.rocks",
    "top_level_domain": "Yes",
    "type": "Professional",
    "disposable": "No",
    "mx_records": [
        "ASPMX3.GOOGLEMAIL.COM.",
        "ASPMX2.GOOGLEMAIL.COM.",
        "ALT2.ASPMX.L.GOOGLE.COM.",
        "ASPMX.L.GOOGLE.COM.",
        "ALT1.ASPMX.L.GOOGLE.COM."
    ],
    "provider": "Google",
    "status": "Invalid",
    "format": "Ok",
    "full_inbox": "Not full",
    "message": "Domain does not have email service set up"
}

Attribute	Type	Description
email	string	Input email address you want to verify.
top level domain	string	Yes/No, if the given email address is from a top level domain list or not.
type	string	Type of domain, can be professional or personal.
disposable	string	Yes/No, if the given email address is from a disposable email service.
mx_records	list	List of MX records that exist on the domain of the given email address.
provider	string	Email provider of the given email address.
status	string	Valid/Invalid/Accept_all
format	string	Correct/Incorrect
full_inbox	string	Full or not full, depending of the inbox status.
message	string	(Optional) Detailed error message about some occurring problem.

Phone Verifier

Intro

Our Phone Verifier API can offer easy way to parse and verify a given phone number, with additional information regarding that number, such as phone provider, country, etc. This API uses Google’s phonenumber library for parsing and validation of a given phone number. When we speak about verification, we must bear in mind the following info that is stated in Google’s phonenumber documentation:

HTTP Request

curl --location --request POST 'https://api.sales.rocks/toolkit/phoneVerifier' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "phones": ["38922037347", "3897820b4075", "78418838"]
}'

Method	URL
POST	https://api.sales.rocks/toolkit/phoneVerifier

Request parameters

Body example:

{
    "phones": [
        "38922037347",
        "3897820b4075",
        "78418838"
    ]
}

As an input, our API receives a JSON object with “phones” as key parameter and a list of phone numbers that you want to verify, as value parameter.

Key parameter	Value parameter
phones	List of phone numbers to be verified

Response attributes

Response example:

[
    {
        "input": "38922037347",
        "status": "VALID",
        "message": "Success",
        "default": "38922037347",
        "country_code": "+389",
        "country_isoCode": "MK",
        "local": "02 203 7347",
        "international": "+389 2 203 7347",
        "number_type": "Fixed Line",
        "country": "Macedonia",
        "location": "Skopje",
        "timezone": [
            "Europe/Skopje"
        ]
    },
    {
        "input": "3897820b4075",
        "status": "INVALID FORMAT",
        "message": "The string supplied did not seem to be a phone number."
    },
    {
        "input": "78418838",
        "status": "INVALID",
        "message": "The phone number entered is not valid."
    }
]

Attribute	Type	Description
input	string	Input phone number you want to verify.
status	string	VALID/INVALID/INVALID FORMAT.
message	string	Success, if the status is VALID, or error message if the status is INVALID/INVALID FORMAT.
default	string	Default format of the phone number, without spaces or dashes.
country_code	string	Country code of the given phone number.
country_isoCode	string	Country ISO code of the given phone number.
local	string	Local format of the given phone number, without country code prefix.
international	string	International format of the given number, with spaces/dashes and starting plus sign.
number_type	string	Type of the given phone number, can be one of the following: Fixed line, Mobile, Fixed line or Mobile, Toll Free, Premium Rate, Shared Cost, VOIP, Personal Number, Pager, UAN, Voicemail, Unknown
country	string	Name of the country for the given phone number, based on country code.
location	string	Location of the given phone number, can be city, state or region.
timezone	list	List of timezones for the given phone number.