Datastone Docs

Overview

The API provides an easy to use Rest API to query and enrich persons and companies data.

Basic Concepts

To use our API you need to be know some concepts:

Credit: A credit is the smallest unit of billing.
- Ex: One line of prospection using the plan 1 can cost X credit, and one line using the plan 3 can cost Y credits.
- * Consult your account manager to check the applicable charges.
Plan: A plan defines a set of fields related to persons and companies. On api the plans are numerically represented from 1 o 3. More details are available below in this documentation.
apiKey: The apiKey is the value used to authenticate on the Datastone API. To authenticate you must provide the HTTP header AUTHORIZATION with the value of your apiKey.
- You can get your apiKey on your profile page
- You must provide the AUTHORIZATION header on the following format:

Plans

When you have to choice who fields you want and you have to do it thru a plan you can use the three available plans: SIMPLE (1) and PREMIUM (3).

Fields of Persons:

1 - SIMPLE: cpf, name, addresses, land_lines, mobile_phones, age, sign.
3 - PREMIUM: cpf, name, address, land_lines, mobile_phones, birthday, gender, emails, mother_name, estimated_income, rg, cbo_code, cbo_description, bolsa_familia, possibly_dead, retired, pep, vehicles, family_persons, related_companies, registry_situation, employer, consumer_profile.

Fields of Companies:

1 - SIMPLE: cnpj, trading_name, company_name, addresses, land_lines, mobile_phones.
3 - PREMIUM: cnpj, trading_name, company_name, addresses, land_lines, mobile_phones, creation_date, related_persons, related_emails, estimated_revenue, employee_count, headquarter_type, business_size, registry_situation, cnae_code, cnae_description, juridical_type_id, juridical_type, vehicles, emails.

Rate Limit

Requests made in both the api and the panel have a limit of 100 requests per day by default. This rule can change at any time without notice.

Some companies or accounts may have this different limit. Contact an administrator for more details.

The company administrator can add ip's to the whitelist. These ip's do not fall under the rate limit rules.

If the stipulated limit is reached, you will only be able to access it again after 24 hours.

If the stipulated limit is reached, the request will be returned a 429 error code.

Prospecting

A prospect searches the database for records that meet the chosen filters. To create a prospecting you can add filters such as activity (cnae), profession, state, city, neighborhood. The api accepts these values in a list, it is not required to pass all filters. To extract the data it is mandatory to pass the fields: plan, name, quantity and at least one location such as a neighborhood, city or state. All plans have a maximum quantity of 250,000 per extraction.

Prospecting Persons:

1 - SIMPLE: cpf, name, addresses, land_lines, mobile_phones.
3 - PREMIUM: cpf, name, address, land_lines, mobile_phones, birthday, gender, emails, mother_name, estimated_income, rg, cbo_code, cbo_description, bolsa_familia, possibly_dead, retired, pep.
4 - WHATSAPP: phone, name, city, uf.

Prospecting Companies:

1 - SIMPLE: cnpj, trading_name, company_name, cnae_code, cnae_description, juridical_type_id, juridical_type, addresses, land_lines, mobile_phones, emails, company_type, nature, mei_type, sector_codes, simple_type, capitals,import_export, vehicles.
3 - PREMIUM: cnpj, trading_name, company_name, cnae_code, cnae_description, juridical_type_id, juridical_type, type, business_size, creation_date, estimated_revenue, employee_count, addresses, land_lines, mobile_phones, emails,company_type, nature, mei_type, sector_codes, simple_type, capitals,import_export, vehicles. Partners data (cnpj, prioridade, cargo, cpf, nome, participação, celulares, fixos, emails).
4 - WHATSAPP: mobile_phone, name, company, city, uf.

P.s. When it is a person prospecting and the email contact channel is selected, you must select at least the intermediate plan.

P.s. To use the whatsapp plan the whatsapp contact channel becomes mandatory.

P.s. When it is a company prospecting and the whatsapp contact channel is selected, the plan must be whatsapp or premium.

enrichment

An enrichment allows uploading data files with CPF or CNPJ and transforming them into enriched files, that is, enrichment is the process that the Data Stone platform performs to enter information from that CPF or CNPJ, it works as an input and output system: - The entry accepts files in (.csv) and (.txt) formats, with the content separated by a semicolon ( ; ) and the only information it should contain is the CPF or CNPJ of the people or entity you want to search for. - The output system allows downloading in (.csv) and (Excel) formats with the information pre selected by the user in File layout.

Webhook

The api has a webhook, this option allows the dev to receive a POST request at the end of each enrichment and prospecting. To add the url just register in the edition of the profile of the user who manages the company account. In the registration of the url a test will be made to check its availability.

Attention

When the completion of a service such as prospecting or enrichment happens, we will send a request to that url with the status.

The registered url must accept a POST type request and return with HTTP 200 status.

Upon receiving the call you should immediately return with this status.

The API will make 3 attempts at 1 minute intervals, all requests have a 30 second timeout.

The following information will be sent in the request body: job id, job type and status. Eg: {"job_id": 1, "job_type": "enrichment", "status": "done"}

Return types expected by the notification API.

Chave	Valor
job_id	1...n
job_type	enrichment prospecting
status	Enrichment requested done error Prospecting requested done error

Chave

Valor

job_id

1...n

job_type

enrichment
prospecting

status

Enrichment

requested
done
error

Prospecting

requested
done
error

Request Example

Code samples to consume the API.

Person Detail

You can make the search only inputing the CPF as parameter in the URL.

Search for a Person by CPF

You can search for a person's information using their CPF (Cadastro de Pessoas Físicas) as a parameter in the URL.

Endpoint

GET https://api.datastone.com.br/v1/persons

Required Query Parameter

cpf: The CPF of the person you want to search for. This should be provided as a query parameter in the URL.

Optional Query Parameter

fields: Specifies which fields to include in the response.

fields=name: Only the person's name will be returned.
fields=all or if the fields parameter is omitted: All available information about the person will be returned.

Example Requests

1. To retrieve only the person's name:

GET https://api.datastone.com.br/v1/persons/?cpf=12345678900&fields=name

Response:


                                        {
                                        "cpf": "12345678900",
                                        "name": "John Doe",
                                        "ip": "127.0.0.1",
                                        "plan": "Consulta Premium"
                                    }

If the fields parameter is not provided, the endpoint defaults to returning all fields available for the person.

                                        
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/persons/?cpf=NUMBER',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/persons/?cpf=NUMBER'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/persons/?cpf=NUMBER';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Person Search

Another person searchs methods.

You can make another search using the following items:

https://api.datastone.com.br/v1/persons/search/

?email, ?phone, ?mother. Using the address(you have to pass atleast two args, ?zip_code &address_number or ?address &address_number)

                                        
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/persons/search/?name=NAME FIRST NAME MIDDLE NAME LAST&uf=SP',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/persons/search/?name=NAME FIRST NAME MIDDLE NAME LAST&uf=SP'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/persons/search/?name=NAME FIRST NAME MIDDLE NAME LAST&uf=SP';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Person Advanced Search

A person advanced search.

You can search people by name in an advanced way using the following endpoint:

https://api.datastone.com.br/v1/persons/advanced-search/

Required params:

name

Optional params:

state, city, search_type

available search_type:
1 - Exact search
2 (default) - Advanced search, Here, you can use the character "*" between the first and last name in order to get people's data regardless of their middle name.
Another values for search_type will raise Client Error Responses

                                        
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/persons/advanced-search/?name=FIRST NAME*LAST&uf=SP&city=São Paulo&search_type=2',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/persons/advanced-search/?name=FIRST NAME*LAST&uf=SP&city=São Paulo&search_type=2'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/persons/advanced-search/?name=FIRST NAME*LAST&uf=SP&city=São Paulo&search_type=2';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Company Detail

You can make the search only inputing the CNPJ as parameter in the URL.

Endpoint

GET https://api.datastone.com.br/v1/companies

Required Query Parameter

CNPJ: The CNPJ of the company you want to search for. This should be provided as a query parameter in the URL.

Optional Query Parameter

fields: Specifies which fields to include in the response.

fields=company_name: Only the company's name will be returned.
fields=all or if the fields parameter is omitted: All available information about the company will be returned.

Example Requests

1. To retrieve only the company's name:

GET https://api.datastone.com.br/v1/companies/?cnpj=12345678000102&fields=company_name

Response:

{
                "cnpj": 12345678000102,
                "company_name": "John Doe Corporation",
                "ip": "127.0.0.1",
                "plan": "Consulta Premium"
}

If the fields parameter is not provided, the endpoint defaults to returning all fields available for the company.

                                        
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.datastone.com.br/v1/companies/?cnpj=NUMBER',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/companies/?cnpj=NUMBER'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/companies/?cnpj=NUMBER';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Company Search

Another company searchs methods.

You can make another search using the following items:

email, domain, cep, phone.

                                        
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/company/list/?razao_social=NAME&uf=SP',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/company/list/?razao_social=NAME&uf=SP'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/company/list/?razao_social=NAME&uf=SP;
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Company Search affiliate

Look for companies that have affiliates.

The value to add to the search is the following.

Examples of successful return:

    {
        "CNPJ": 12345678912345,
        "RAIZ_CNPJ": 1234567,
        "DS_MATRIZ_FILIAL": "MATRIZ"
    },
    {
        "CNPJ": 2107841000370,
        "RAIZ_CNPJ": 1234567,
        "DS_MATRIZ_FILIAL": "FILIAL"
    },

Return example not found:

{
     []
}

                                        
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/company/search/filial/?cnpj=NUMBER',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Many companies have affiliates.

The value to add to the searach is the following.

Examples of successful return:

    {
        "CNPJ": 12345678912345,
        "RAIZ_CNPJ": 1234567,
        "DS_MATRIZ_FILIAL": "MATRIZ"
    },
    {
        "CNPJ": 2107841000370,
        "RAIZ_CNPJ": 1234567,
        "DS_MATRIZ_FILIAL": "FILIAL"
    },

Return example not found:

{
     []
}

                                                
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/company/search/filial/?cnpj=NUMBER'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Many companies have affiliates.

The value to add to the searach is the following.

Examples of successful return:

    {
        "CNPJ": 12345678912345,
        "RAIZ_CNPJ": 1234567,
        "DS_MATRIZ_FILIAL": "MATRIZ"
    },
    {
        "CNPJ": 2107841000370,
        "RAIZ_CNPJ": 1234567,
        "DS_MATRIZ_FILIAL": "FILIAL"
    },

Return example not found:

{
     []
}

                                    
var url = 'https://api.datastone.com.br/v1/company/search/filial/?cnpj=NUMBER';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Cnae

Request available cnae

The value to add to the cnae list in the prospecting is code

                                                
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/cnae/?description=cnae_description_or_code',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Request available cnae

The value to add to the cnae list in the prospecting is code

                                                
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/cnae/?description=cnae_description_or_code'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Request available cnae

The value to add to the cnae list in the prospecting is code

                                                
var url = 'https://api.datastone.com.br/v1/cnae/?description=cnae_description_or_code';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Profession

Request available profession

The value to add to the profession list in the prospecting is code

                                                
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/cbo/?description=profession_description_or_code',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Request available profession

The value to add to the profession list in the prospecting is code

                                                
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/cbo/?description=profession_description_or_code'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Request available profession

The value to add to the profession list in the prospecting is code

                                                
var url = 'https://api.datastone.com.br/v1/cbo/?description=profession_description_or_code';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

City

Request available city

The value to add to the city list in the prospecting is value

                                                
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/geo/city/?name=city_name&state=acronym_state',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Request available city

The value to add to the city list in the prospecting is value

                                                
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/geo/city/?name=city_name&state=acronym_state'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Request available city

The value to add to the city list in the prospecting is value

                                                
var url = 'https://api.datastone.com.br/v1/geo/city/?name=city_name&state=acronym_state';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Neighborhood

Request available neighborhood

The value to add to the neighborhood list in the prospecting is value

                                                
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/geo/neighborhood/?name=neighborhood_name&city=city_name',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Request available neighborhood

The value to add to the neighborhood list in the prospecting is value

                                                
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/geo/neighborhood/?name=neighborhood_name&city=city_name'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Request available neighborhood

The value to add to the neighborhood list in the prospecting is value

                                                
var url = 'https://api.datastone.com.br/v1/geo/neighborhood/?name=neighborhood_name&city=city_name';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

State

The states are informed in the prospect list only the acronym. Ex. "AC", "MG", "SP", "RJ". Available options:

"AC", "AL", "AM", "AP", "BA", "CE", "DF", "ES", "GO", "MA", "MG", "MS", "MT", "PA", "PB", "PE", "PI", "PR", "RJ", "RN", "RO", "RR", "RS", "SC", "SE", "SP", "TO"

Sector Cnae

Request available sector cnae

To request the available sector cnaes check out the followings examples below:

NOTE: to use it in prospection use the return "description" field, as it was returned from this API.

                                            
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/sector/cnae/',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Request available sector cnae

To request the available sector cnaes check out the followings examples below:

NOTE: to use it in prospection use the return "description" field, as it was returned from this API.

                                            
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/sector/cnae/'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Request available sector cnae

To request the available sector cnaes check out the followings examples below:

NOTE: to use it in prospection use the return "description" field, as it was returned from this API.

                                            
var url = 'https://api.datastone.com.br/v1/sector/cnae/';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Person Profile

Request available person profiles

To request the available profiles check out the followings examples below:

NOTE: to use it in prospection use the return "code" field, as it was returned from this API.

                                            
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/persons/prospect/profile/',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Request available person profiles

To request the available profiles check out the followings examples below:

NOTE: to use it in prospection use the return "code" field, as it was returned from this API.

                                            
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/persons/prospect/profile/'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

Request available person profiles

To request the available profiles check out the followings examples below:

NOTE: to use it in prospection use the return "code" field, as it was returned from this API.

                                            
var url = 'https://api.datastone.com.br/v1/persons/prospect/profile/';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Person Prospection

Request available persons count

The available filters for prospecting people are: cities, states, neighborhoodies, gender, cbo_codes, estimated_income, birthday, age, contact_channels, match_profile. To extract the data it is necessary to pass in the json the fields: plan, quantity, name, export and at least one location filter such as: neighborhoodies, cities or states.

                                                
$ch = curl_init();
$data = array("name" => "Sample name",
    "cities" => array("BELO HORIZONTE - MG"),
    "states" => array("MG"),
    "contact_channels" => array("whatsapp", "email"),
    "match_profile" => array("PF1", "PF3"),
    "gender" => "M",
    "export" => false
);
$data_string = json_encode($data);
curl_setopt_array($ch, [
    CURLOPT_POST => false,
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/persons/prospect/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Send prospection request

                                                
$ch = curl_init();
$data = array("name" => "Sample name",
    "cities" => array("BELO HORIZONTE - MG"),
    "states" => array("MG"),
    "contact_channels" => ("whatsapp", "email"),
    "match_profile" => array("PF1", "PF3"),
    "gender" => "M",
    "export" => true,
    "quantity" => 10,
    "callback_email" => "[email protected]",
    "plan" => 1
);
$data_string = json_encode($data);
curl_setopt_array($ch, [
    CURLOPT_POST => false,
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/persons/prospect/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Save prospection filter request

The filter_type must be 1

                                            
$ch = curl_init();
$data = array(
    "data" => array(
        "name" => "Sample Prospection name",
        "cities" => ("BELO HORIZONTE - MG"),
        "states" => ("MG"),
        "contact_channels" => ("whatsapp", "email"),
        "match_profile" => ("PF1", "PF3"),
        "gender" => "M",
        "export" => true,
        "quantity" => 10,
        "plan" => 3
    ),
    "filter_name" => "Sample Filter Name",
    "filter_type" => 1
);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/prospection/filters/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);

echo curl_exec($ch);
curl_close($ch);

List prospection filter request

NOTE: if "list_person" is present in the URL parameter it should return all the saved filters otherwise if you use the following example it should return only the filter that you want https://api.datastone.com.br/v1/prospection/filters/<'id'>

                                            
$ch = curl_init();
$url = 'https://api.datastone.com.br/v1/prospection/filters/list_person';
$headers = [
    'Authorization: apiKey',
    'Content-Type: application/json'
];

curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);

$result = curl_exec($ch);
echo $result;
curl_close($ch);

Request available persons count

                                                
# pip install requests
import json
import requests

url = 'https://api.datastone.com.br/v1/persons/prospect/'
headers = {"Authorization": "apiKey"}
payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"], "contact_channels": ["whatsapp","email"],"match_profile": ["PF1", "PF3"], "gender": "M", "export": False}
data = requests.post(url, data=json.dumps(payload), headers=headers)
print(data.json())

Send prospection request

                                            
# pip install requests
import json
import requests

url = 'https://api.datastone.com.br/v1/persons/prospect/'
headers = {"Authorization": "apiKey"}
payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"], "contact_channels": ["whatsapp", "email"], "match_profile": ["PF1", "PF3"], "gender": "M", "export": True, "quantity": 10,
            "callback_email": "[email protected]", "plan": 1}
data = requests.post(url, data=json.dumps(payload), headers=headers)
print(data.json())

Save prospection filter request

The filter_type must be 1

                                        
# pip install requests
import requests
import json

url = 'https://api.datastone.com.br/v1/prospection/filters/'
headers = {
    'Authorization': 'apiKey',
    'Content-Type': 'application/json',
}

data = {
    "data": {
        "name": "Sample Prospection name",
        "cities": ["BELO HORIZONTE - MG"],
        "states": ["MG"],
        "contact_channels": ["whatsapp", "email"],
        "match_profile": ["PF1", "PF3"],
        "gender": "M",
        "export": True,
        "quantity": 10,
        "plan": 3
    },
    "filter_name": "Sample Filter Name",
    "filter_type": 1
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.text)

List prospection filter request

                                        
url = 'https://api.datastone.com.br/v1/prospection/filters/list_person'
headers = {
    'Authorization': 'apiKey',
    'Content-Type': 'application/json',
}

response = requests.get(url, headers=headers)

print(response.text)

Request available persons count

                                            
var url = 'https://api.datastone.com.br/v1/persons/prospect/';
var headers = {"Authorization": "apiKey"};
var payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"], "contact_channels": ["whatsapp", "email"], "match_profile": ["PF1", "PF3"], "gender": "M", "export": false};
$.ajax({
    type: "POST",
    url: url,
    data: JSON.stringify(payload),
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Send prospection request

                                                
var url = 'https://api.datastone.com.br/v1/persons/prospect/';
var headers = {"Authorization": "apiKey"};
var payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"], "contact_channels": ["whatsapp","email"], "match_profile": ["PF1", "PF3"], "gender": "M", "export": true, "quantity": 10,
            "callback_email": "[email protected]", "plan": 1};
$.ajax({
    type: "POST",
    url: url,
    data: JSON.stringify(payload),
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Save prospection filter request

The filter_type must be 1

                                            
var url = 'https://api.datastone.com.br/v1/prospection/filters/';
var headers = { "Authorization": "apiKey" };
var payload = {
    "data": {
        "name": "Sample Prospection name",
        "cities": ["BELO HORIZONTE - MG"],
        "states": ["MG"],
        "contact_channels": ["whatsapp", "email"],
        "match_profile": ["PF1", "PF3"],
        "gender": "M",
        "export": true,
        "quantity": 10,
        "plan": 3
    },
    "filter_name": "Sample Filter Name",
    "filter_type": 1
};

$.ajax({
    type: "POST",
    url: url,
    data: JSON.stringify(payload),
    headers: headers,
    contentType: "application/json",
    success: function (data) {
        console.log(data);
    },
    error: function (error) {
        console.log(error);
    }
});

List prospection filter request

                                            
var url = 'https://api.datastone.com.br/v1/prospection/filters/list_person';
var headers = {
    'Authorization': 'apiKey',
    'Content-Type': 'application/json'
};

$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function (data) {
        console.log(data);
    },
    error: function (error) {
        console.log(error);
    }
});

Company Prospection

Request available company count

The available filters for prospecting companies are: cities, states, neighborhoodies, estimated_employees, headquarter_type, estimated_created, contact_channels, cbo_codes, cnae_codes, revenues, company_type, nature_codes, mei_type, sector_cnae, simple_type, capitals, import_export, vehicles. To extract the data it is necessary to pass in the json the fields: plan, quantity, name, export and at least one location filter such as: neighborhoodies, cities or states.

                                                
$ch = curl_init();
$data = array("name" => "Sample name",
    "cities" => array("BELO HORIZONTE - MG"),
    "states" => array("MG"),
    "headquarter_type" => "H",
    "estimated_employees" => array(
        array("lower" => 3, "upper" => 12)
    ),
    "estimated_created" => array(
        array("lower" => "1990-01-20", "upper" => "2000-12-31")
    ),
    "cnae_codes" => array(
        "8550301"
    ),
    "revenues" => array(
        array("lower" => "50000.00", "upper" => "125000.00")
    ),
    "company_type" => "ME",

    "nature_codes" => array(
        "2291"
    ),
    "mei_type" => "NAO",

    "sector_codes" => array(
        "INDUSTRIA", "SERVIÇO", "EDUCAÇÃO"
    ),
    "simple_type" => "SIM",

    "capitals" => array(
        array("lower" => "50000.00", "upper" => "125000.00")
    ),
    "import_export" => "EXPORTA",

    "vehicles" => array(
        array("lower" => "1", "upper" => "5000")
    ),
    "export" => false
);
$data_string = json_encode($data);
curl_setopt_array($ch, [
    CURLOPT_POST => false,
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/company/prospect/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Send prospection request

                                                
$ch = curl_init();
$data = array("name" => "Sample name",
    "cities" => array("BELO HORIZONTE - MG"),
    "states" => array("MG"),
    "headquarter_type" => "H",
    "estimated_employees" => array(
        array("lower"=> 3, "upper"=> 12)
    ),
    "estimated_created" => array(
        array("lower"=> "1990-01-20", "upper"=> "2000-12-31")
    ),
    "cnae_codes" => array(
        "8550301"
    ),
    "revenues" => array(
        array("lower"=> "50000.00", "upper"=> "125000.00")
    ),
    "company_type" => "ME",

    "nature_codes" => array(
        "2291"
    ),
    "mei_type" => "NAO",

    "sector_codes" => array(
        "INDUSTRIA", "SERVIÇO", "EDUCAÇÃO"
    ),
    "simple_type" => "SIM",

    "capitals" => array(
        array("lower" => "50000.00", "upper" => "125000.00")
    ),
    "import_export" => "EXPORTA",

    "vehicles" => array(
        array("lower" => "1", "upper" => "5000")
    ),
    "export" => true,
    "quantity" => 10,
    "callback_email" => "[email protected]",
    "plan" => 1
);
$data_string = json_encode($data);
curl_setopt_array($ch, [
    CURLOPT_POST => false,
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/company/prospect/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

Save prospection filter request

The filter_type must be 2

                                            
$ch = curl_init();
$data = array(
    "data" => array(
        "name" => "Sample name",
        "cities" => array("BELO HORIZONTE - MG"),
        "states" => array("MG"),
        "headquarter_type" => "H",
        "estimated_employees" => array(
            array("lower"=> 3, "upper"=> 12)
        ),
        "estimated_created" => array(
            array("lower"=> "1990-01-20", "upper"=> "2000-12-31")
        ),
        "cnae_codes" => array(
            "8550301"
        ),
        "revenues" => array(
            array("lower"=> "50000.00", "upper"=> "125000.00")
        ),
        "company_type" => "ME",
        "nature_codes" => array(
            "2291"
        ),
        "mei_type" => "NAO",
        "sector_codes" => array(
            "INDUSTRIA", "SERVIÇO", "EDUCAÇÃO"
        ),
        "simple_type" => "SIM",
        "capitals" => array(
            array("lower" => "50000.00", "upper" => "125000.00")
        ),
        "import_export" => "EXPORTA",
        "vehicles" => array(
            array("lower" => "1", "upper" => "5000")
        ),
        "export" => true,
        "quantity" => 10,
        "callback_email" => "[email protected]",
        "plan" => 3
    ),
    "filter_name" => "Sample Filter Name",
    "filter_type" => 2
);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/prospection/filters/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

List prospection filter request

NOTE: if "list_company" is present in the URL parameter it should return all the saved filters otherwise if you use the following example it should return only the filter that you want https://api.datastone.com.br/v1/prospection/filters/<'id'>

                                            
$ch = curl_init();
$url = 'https://api.datastone.com.br/v1/prospection/filters/list_company';
$headers = [
    'Authorization: apiKey',
    'Content-Type: application/json'
];
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
$result = curl_exec($ch);
echo $result;
curl_close($ch);

Save prospection filter request

The filter_type must be 2

                                            
$ch = curl_init();
$data = array(
    "data" => array(
        "name" => "Sample name",
        "cities" => array("BELO HORIZONTE - MG"),
        "states" => array("MG"),
        "headquarter_type" => "H",
        "estimated_employees" => array(
            array("lower"=> 3, "upper"=> 12)
        ),
        "estimated_created" => array(
            array("lower"=> "1990-01-20", "upper"=> "2000-12-31")
        ),
        "cnae_codes" => array(
            "8550301"
        ),
        "revenues" => array(
            array("lower"=> "50000.00", "upper"=> "125000.00")
        ),
        "company_type" => "ME",
        "nature_codes" => array(
            "2291"
        ),
        "mei_type" => "NAO",
        "sector_codes" => array(
            "INDUSTRIA", "SERVIÇO", "EDUCAÇÃO"
        ),
        "simple_type" => "SIM",
        "capitals" => array(
            array("lower" => "50000.00", "upper" => "125000.00")
        ),
        "import_export" => "EXPORTA",
        "vehicles" => array(
            array("lower" => "1", "upper" => "5000")
        ),
        "export" => true,
        "quantity" => 10,
        "callback_email" => "[email protected]",
        "plan" => 3
    ),
    "filter_name" => "Sample Filter Name",
    "filter_type" => 2
);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/prospection/filters/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);

echo curl_exec($ch);
curl_close($ch);

List prospection filter request

                                            
$ch = curl_init();
$url = 'https://api.datastone.com.br/v1/prospection/filters/list_company';
$headers = [
    'Authorization: apiKey',
    'Content-Type: application/json'
];

curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);

$result = curl_exec($ch);
echo $result;
curl_close($ch);

Request available company count

                                                
# pip install requests
import json
import requests

url = 'https://api.datastone.com.br/v1/company/prospect/'
headers = {"Authorization": "apiKey"}
payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"], "headquarter_type": "H",
            "estimated_employees": [{"lower": 3, "upper": 12}],
            "estimated_created": [{"lower": "1990-01-20", "upper": "2000-12-31"}],
            "cnae_codes": ["8550301"],
            "revenues": [{"lower": "50000.00", "upper": "125000.00"}],
            "nature_codes":["2291","2330","2143"],
            "sector_codes":["INDUSTRIA","SERVIÇO","SAÚDE/SERVIÇOS SOCIAIS","EDUCAÇÃO"],
            "capitals":[{"lower":"1000.00","upper":"900000.00"}],
            "vehicles":[{"lower":"1","upper":"2000"}],
            "mei_type":"NAO",
            "simple_type":"SIM",
            "import_export":"EXPORTA",
            "company_type":"DEMAIS",
            "export": False}
data = requests.post(url, data=json.dumps(payload), headers=headers)
print(data.json())

Send prospection request

                                                
# pip install requests
import json
import requests

url = 'https://api.datastone.com.br/v1/company/prospect/'
headers = {"Authorization": "apiKey"}
payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"],  "headquarter_type": "H",
            "estimated_employees": [{"lower": 3, "upper": 12}],
            "estimated_created": [{"lower": "1990-01-20", "upper": "2000-12-31"}],
            "cnae_codes": ["8550301"],
            "revenues": [{"lower": "50000.00", "upper": "125000.00"}],
            "nature_codes":["2291","2330","2143"],
            "sector_codes":["INDUSTRIA","SERVIÇO","SAÚDE/SERVIÇOS SOCIAIS","EDUCAÇÃO"],
            "capitals":[{"lower":"1000.00","upper":"900000.00"}],
            "vehicles":[{"lower":"1","upper":"2000"}],
            "mei_type":"NAO",
            "simple_type":"SIM",
            "import_export":"EXPORTA",
            "company_type":"DEMAIS",
            "export": True, "quantity": 10,
            "callback_email": "[email protected]", "plan": 1}
data = requests.post(url, data=json.dumps(payload), headers=headers)
print(data.json())

Save prospection filter request

The filter_type must be 1

                                            
    # pip install requests
    import requests
    import json

    url = 'https://api.datastone.com.br/v1/prospection/filters/'

    data = {
        "data": {
            "name": "Sample name",
            "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"],
            "headquarter_type": "H",
            "estimated_employees": [{"lower": 3, "upper": 12}],
            "estimated_created": [{"lower": "1990-01-20", "upper": "2000-12-31"}],
            "cnae_codes": ["8550301"],
            "revenues": [{"lower": "50000.00", "upper": "125000.00"}],
            "company_type": "ME",
            "nature_codes": ["2291"],
            "mei_type": "NAO",
            "sector_codes": ["INDUSTRIA", "SERVIÇO", "EDUCAÇÃO"],
            "simple_type": "SIM",
            "capitals": [{"lower": "50000.00", "upper": "125000.00"}],
            "import_export": "EXPORTA",
            "vehicles": [{"lower": "1", "upper": "5000"}],
            "export": True,
            "quantity": 10,
            "callback_email": "[email protected]",
            "plan": 3
        },
        "filter_name": "Sample Filter Name",
        "filter_type": 2
    }

    headers = {
        'Authorization': 'apiKey',
        'Content-Type': 'application/json',
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    print(response.text)

List prospection filter request

                                            
    # pip install requests
    import requests

    url = 'https://api.datastone.com.br/v1/prospection/filters/list_company'
    headers = {
        'Authorization': 'apiKey',
        'Content-Type': 'application/json',
    }

    response = requests.get(url, headers=headers)

    print(response.text)

Request available company count

                                                
var url = 'https://api.datastone.com.br/v1/company/prospect/';
var headers = {"Authorization": "apiKey"};
var payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"],  "headquarter_type": "H",
            "estimated_employees": [{"lower": 3, "upper": 12}],
            "estimated_created": [{"lower": "1990-01-20", "upper": "2000-12-31"}],
            "cnae_codes": ["8550301"],
            "revenues": [{"lower": "50000.00", "upper": "125000.00"}],
            "nature_codes":["2291","2330","2143"],
            "sector_codes":["INDUSTRIA","SERVIÇO","SAÚDE/SERVIÇOS SOCIAIS","EDUCAÇÃO"],
            "capitals":[{"lower":"1000.00","upper":"900000.00"}],
            "vehicles":[{"lower":"1","upper":"2000"}],
            "mei_type":"NAO",
            "simple_type":"SIM",
            "import_export":"EXPORTA",
            "company_type":"DEMAIS",
            "export": false};
$.ajax({
    type: "POST",
    url: url,
    data: JSON.stringify(payload),
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Send prospection request

                                                
var url = 'https://api.datastone.com.br/v1/company/prospect/';
var headers = {"Authorization": "apiKey"};
var payload = {"name": "Sample name", "cities": ["BELO HORIZONTE - MG"],
            "states": ["MG"],  "headquarter_type" : "H",
            "estimated_employees": [{"lower": 3, "upper": 12}],
            "estimated_created": [{"lower": "1990-01-20", "upper": "2000-12-31"}],
            "cnae_codes": ["8550301"],
            "revenues": [{"lower": "50000.00", "upper": "125000.00"}],
            "nature_codes":["2291","2330","2143"],
            "sector_codes":["INDUSTRIA","SERVIÇO","SAÚDE/SERVIÇOS SOCIAIS","EDUCAÇÃO"],
            "capitals":[{"lower":"1000.00","upper":"900000.00"}],
            "vehicles":[{"lower":"1","upper":"2000"}],
            "mei_type":"NAO",
            "simple_type":"SIM",
            "import_export":"EXPORTA",
            "company_type":"DEMAIS",
            "export": true, "quantity": 10,
            "callback_email": "[email protected]", "plan": 1};
$.ajax({
    type: "POST",
    url: url,
    data: JSON.stringify(payload),
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Save prospection filter request

The filter_type must be 2

                                            
var url = 'https://api.datastone.com.br/v1/prospection/filters/';
var headers = {"Authorization": "apiKey"};
var data = {
    "data": {
        "name": "Sample name",
        "cities": ["BELO HORIZONTE - MG"],
        "states": ["MG"],
        "headquarter_type": "H",
        "estimated_employees": [{"lower": 3, "upper": 12}],
        "estimated_created": [{"lower": "1990-01-20", "upper": "2000-12-31"}],
        "cnae_codes": ["8550301"],
        "revenues": [{"lower": "50000.00", "upper": "125000.00"}],
        "company_type": "ME",
        "nature_codes": ["2291"],
        "mei_type": "NAO",
        "sector_codes": ["INDUSTRIA", "SERVIÇO", "EDUCAÇÃO"],
        "simple_type": "SIM",
        "capitals": [{"lower": "50000.00", "upper": "125000.00"}],
        "import_export": "EXPORTA",
        "vehicles": [{"lower": "1", "upper": "5000"}],
        "export": true,
        "quantity": 10,
        "callback_email": "[email protected]",
        "plan": 3
    },
    "filter_name": "Sample Filter Name",
    "filter_type": 2
};

$.ajax({
    type: "POST",
    url: url,
    data: JSON.stringify(data),
    headers: headers,
    contentType: "application/json",
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

List prospection filter request

                                            
var url = 'https://api.datastone.com.br/v1/prospection/filters/list_company';
var headers = {
    'Authorization': 'apiKey',
    'Content-Type': 'application/json'
};

$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Get prospection file

After receiving a response from the webhook notifying that the prospection status is done, access the endpoint so the prospection download link will be available.

In the example below, '1234' is the job id returned from the webhook

                      
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/prospection/1234/result/',
CURLOPT_HTTPHEADER => [
'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);


# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/prospection/1234/result/'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())


var url = 'https://api.datastone.com.br/v1/prospection/1234/result/';
var headers = {"Authorization": "apiKey"};
$.ajax({
type: "GET",
url: url,
headers: headers,
success: function(data) {
console.log(data);
},
error: function(error) {
console.log(error);
}
});

Enrichment

Request available layouts

                                            
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_POST => false,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/enrichment/layouts/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                            
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/enrichment/layouts/'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                            
var url = 'https://api.datastone.com.br/v1/enrichment/layouts/';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Send enrichment request

                                            
$ch = curl_init();
$file = base64_encode(file_get_contents('your-file.csv'));
$data = array("name" => "Enrichment name",
              "layout_id" => 1,
              "parameters" => ["4","2"],
              "file" => $file,
              "callback_email" => "[email protected]");
$data_string = json_encode($data);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/enrichment/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type:application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                            
# pip install requests
import base64
import json
import requests

url = "https://api.datastone.com.br/v1/enrichment/"
headers = {"Authorization": "apiKey", "Content-Type": "application/json"}
file = base64.b64encode(open('your-file.csv', "rb").read())
data = {}
data['name'] = "Enrichment name"
data['layout_id'] = 1
data['parameters'] = ["4", "2"]
data['file'] = file.decode("utf-8")
data['callback_email'] = "[email protected]"
result = requests.post(url, headers=headers, data=json.dumps(data))
print(result.json())

                                            
var url = 'https://api.datastone.com.br/v1/enrichment/';
var headers = {"Authorization": "apiKey"};
var reader = new FileReader();
reader.readAsDataURL("your-file.csv");
reader.onload = function() {
    var form = {};
    form.file = reader.result.split('base64,')[1];
    form.name = "Enrichment name";
    form.layout_id = 1;
    form.parameters = ["4", "2"];
    $.ajax({
        type: "POST",
        url: url,
        data: JSON.stringify(form),
        headers: headers,
        contentType:"application/json",
        success: function(data) {
            console.log(data);
        },
        error: function(error) {
            console.log(error);
        }
    });
}
reader.onerror = function(error) {
    console.log(error);
}

Get enrichment file

After receiving a response from the webhook notifying that the enrichment status is done, access the endpoint so the enrichment download link will be available.

In the example below, '1234' is the job id returned from the webhook

                                            
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/enrichment/1234/result/',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

    
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/enrichment/1234/result/'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

    
var url = 'https://api.datastone.com.br/v1/enrichment/1234/result/';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Webhook

What's a webhook?

It is a way of receiving information when an event happens. Webhook in practice is the way to receive information between two systems in a passive way.

How to configure?

If you want to receive notifications of events happening in the prospecting and enrichment, you must have in your api an endpoint to receive this call that we will make with some data. With this url configured, you must go to the "My Profile" menu and access the "Edit" option. Just below the personal data has a form to add to the url, you must enter the url for example: https://site.com.br/endpoint/. In this form it is also possible to remove or update the registered url. The system will send notification only if you have a valid url registered.

Important Details

When the completion of a service such as prospecting or enrichment we will send a request to this url with the status.
The registered url must accept POST request and return with HTTP 200 status.
Upon receiving the call you should immediately return with this status.
The API will perform 3 retries 1 minute apart, all requests have a 30 second timeout.
The following information will be sent in the request body: job id, job type and status. Ex: {"job_id": 1, "job_type": "enrichment", "status": "requested"}
Return types expected by the notification API.

Key	Value
job_id	1...n
job_type	enrichment prospecting
status	Enrichment requested done error Prospecting requested done error

Key

Value

job_id

1...n

job_type

enrichment
prospecting

status

Enrichment

requested
done
error

Prospecting

requested
done
error

Whatsapp Status

The whatsapp status query returns whether the contact is active, inactive or not found. The ddd and telephone parameters are mandatory. The ddd must be 2 digits and the telephone at most 9 digits, must be passed separately. Passing special characters such as "-" is not allowed. The return to an active or inactive phone has a status code 200 whereas a phone that was not found will have a status code 404

Examples of successful return:

{
     "status": "ATIVO"
}
{
     "status": "INATIVO"
}

Return example not found:

{
     "detail": "Não encontrado."
}

Whatsapp Status Detail

                                
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/whatsapp/search/?ddd=11&phone=111111111',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/whatsapp/search/?ddd=11&phone=111111111'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/whatsapp/search/?ddd=11&phone=111111111';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

Whatsapp Status Batch

The status query of active whatsapp in batch allows you to pass as a parameter in the post a callback url and a list of phones in which each phone has a maximum size of 11 characters for example: 22911111111 (ddd + 9 + phone). When making the call this query will be saved in the system and you receive the processing id, the return of this call is 201 (created) in case of success or 400 (bad request) in case of error, such as: mandatory callback url and in an invalid format, example: foo.com and the correct one would be https://foo.com. The phone list must be an array and have at least one contact. As soon as the search for the status of the sent contacts is finished, a POST call with content type application / json with the sent contacts and their respective status will be sent to the url defined as the callback.

Examples of successful return:

{
     "id": 42
}

Return example bad request:

{
    "callback_url": [
        "Este campo não pode ser em branco.",
        "Entrar um URL válido."
    ],
    "phones": [
        "Esse campo requer ao menos 1 elemento."
    ]
}

Whatsapp Status Batch Examples

                                
$data = array("callback_url" => "https://foo.com/my-path/",
    "phones" => array("11987654321", "41987654321", "13977754123"));
$data_string = json_encode($data);
curl_setopt_array($ch, [
    CURLOPT_POST => false,
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_URL => 'https://api.datastone.com.br/v1/whatsapp/batch/',
    CURLOPT_HTTPHEADER => [
        'Authorization: apiKey',
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

/*
Payload enviado para a callback url

{
  "result": [
    {
      "phone": "41987654321",
      "status": "ATIVO"
    },
    {
      "phone": "11987654321",
      "status": "INATIVO"
    },
    {
      "phone": "13977754123",
      "status": "NAO LOCALIZADO"
    }
  ]
}

*/

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/whatsapp/batch/'
headers = {"Authorization": "apiKey"}
payload = {"callback_url": "https://foo.com/my-path/", "phones": ["11987654321", "41987654321", "13977754123"]}
result = requests.post(url, headers=headers, json=payload)
print(result.json())

"""
Payload enviado para a callback url

{
  "result": [
    {
      "phone": "41987654321",
      "status": "ATIVO"
    },
    {
      "phone": "11987654321",
      "status": "INATIVO"
    },
    {
      "phone": "13977754123",
      "status": "NAO LOCALIZADO"
    }
  ]
}

"""

                                        
var url = 'https://api.datastone.com.br/v1/whatsapp/batch/';
var headers = {"Authorization": "apiKey"};
var payload = {"callback_url": "https://foo.com/my-path/", "phones": ["11987654321", "41987654321", "13977754123"]}
$.ajax({
    type: "POST",
    url: url,
    headers: headers,
    data: JSON.stringify(payload),
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});

/*
Payload enviado para a callback url

{
  "result": [
    {
      "phone": "41987654321",
      "status": "ATIVO"
    },
    {
      "phone": "11987654321",
      "status": "INATIVO"
    },
    {
      "phone": "13977754123",
      "status": "NAO LOCALIZADO"
    }
  ]
}

*/

Balance

                                
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.datastone.com.br/v1/balance',
CURLOPT_HTTPHEADER => [
    'Authorization: apiKey'
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS
]);
echo curl_exec($ch);
curl_close($ch);

                                        
# pip install requests
import requests

url = 'https://api.datastone.com.br/v1/balance'
headers = {"Authorization": "apiKey"}
data = requests.get(url, headers=headers)
print(data.json())

                                        
var url = 'https://api.datastone.com.br/v1/balance';
var headers = {"Authorization": "apiKey"};
$.ajax({
    type: "GET",
    url: url,
    headers: headers,
    success: function(data) {
        console.log(data);
    },
    error: function(error) {
        console.log(error);
    }
});