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 CodeResponseDescription
200OKEverything worked as expected.
400Bad RequestThe 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.
401UnauthorizedNo valid API key provided, the client is not authorized to access the requested resource.
403ForbiddenThe API key doesn't have permissions to perform the request, the client is not authenticated.
404Not FoundThe requested resource doesn't exist.
429Too Many RequestsThe client is sending more than the allowed number of requests per unit time.
500Server ErrorSomething 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:

MethodURL
POSThttps://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 parameterValue parameter
usernameusername that you use to log in on the platform.
passwordpassword 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
}
AttributeTypeDescription
access_tokenstringThe access token string as issued by the authorization server.
token_typestringThe type of token this is, typically just the string “Bearer”.
expires_instringThe 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.

KeyValue
AuthorizationBearer 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"
}'
MethodURL
POSThttps://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 parameterValue parameter
emailEmail 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"
}
AttributeTypeDescription
emailstringInput email address you want to verify.
top level domainstringYes/No, if the given email address is from a top level domain list or not.
typestringType of domain, can be professional or personal.
disposablestringYes/No, if the given email address is from a disposable email service.
mx_recordslistList of MX records that exist on the domain of the given email address.
providerstringEmail provider of the given email address.
statusstringValid/Invalid/Accept_all
formatstringCorrect/Incorrect
full_inboxstringFull or not full, depending of the inbox status.
messagestring(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"]
}'
MethodURL
POSThttps://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 parameterValue parameter
phonesList 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."
}
]
AttributeTypeDescription
inputstringInput phone number you want to verify.
statusstringVALID/INVALID/INVALID FORMAT.
messagestringSuccess, if the status is VALID, or error message if the status is INVALID/INVALID FORMAT.
defaultstringDefault format of the phone number, without spaces or dashes.
country_codestringCountry code of the given phone number.
country_isoCodestringCountry ISO code of the given phone number.
localstringLocal format of the given phone number, without country code prefix.
internationalstringInternational format of the given number, with spaces/dashes and starting plus sign.
number_typestringType 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
countrystringName of the country for the given phone number, based on country code.
locationstringLocation of the given phone number, can be city, state or region.
timezonelistList of timezones for the given phone number.