Company Search

In this tutorial we’ll see how to use the Company Search API to find companies based on some search criterias, like the ATECO sector (the Italian implementation of NACE).

Useful resources

• Documentation of the Company Search API we will be using;
• JS Fiddle with the tutorial code, the bottom right panel is working, enter your token and submit…
• Here you can check the credits available and used on your token, and here you can find detailed information about credits.

Let’s start!

The search API offers us many parameters to filter results; in this tutorial we want to find potential customers among new companies (those with less than one year of activity) in the agricultural sector, and we would like to contact them via email (hence we would like to retrieve only results for which at least one email address is known).

The parameters we will be using are

• ateco = 01 to get only companies in the agricultural sector
• ageMax = 12 to filter out companies older than 12 months
• emails = * to get only companies for which any kind of email is known

GET https://api.atoka.io/v2/companies?packages=base,contacts&ateco=01&ageMax=12&emails=*&token=TOKEN

The response, edited to be more concise, contains:

• items: the list of results, companies in this case,
• meta: it contains the number of results, the ordering, limit, and offset.. Useful for pagination and ordering
• id: is the id Atoka uses to identify the company, used in many other APIs
• name, fullAddress: the information we needed!
• base: it contains the information provided by the base package, address details, ATECO code, legal form, foundation date, and more
• contacts: it contains the information provided by the contacts package, the known email addresses, phone numbers with details about the (secondary) location

{
    "items": [{
            "id": "6da785b3adf2",
            "name": "SPAZIODATI S.R.L.",
            "country": "it",
            "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
            "base": {
                "legalName": "SPAZIODATI S.R.L.",
                "vat": "02241890223",
                "founded": "2019-02-13",
                "ateco": [{
                    "code": "01.24.00",
                    "description": "Coltivazione di pomacee e frutta a nocciolo",
                    "rootCode": "A"
                }],
                "legalForms": [ ... ],
                "registeredAddress": { ... }
            },
            "contacts": {
                "emails": [{
                    "address": "info@spaziodati.eu",
                    "type": "info",
                    "verified": true
                }],
                "phones": [{
                    "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
                    "locationId": "0ef76064b441",
                    "number": "+39 1234 567890",
                    "source": "phone books",
                    "verified": true
                }]
            }
        }, ...],
    "meta": {
        "count": 129,
        "limit": 10,
        "offset": 0,
        "ordering": "atoka"
    }
}

With this request we retrieve only 10 results, but from the content of meta we can see that there are 129 total companies that could be our future customers. To see all other companies it is possible to use the limit and offset parameters to paginate.

// to get the next 10 results
GET https://api.atoka.io/v2/companies?packages=base,contacts&ateco=01&ageMax=12&emails=*&token=TOKEN&limit=10&offset=10 

How much does it cost?

Every company with at least one data package costs 1 credit. The example request will consume 10 companies:* credits, because the API returned 10 companies, and for each of them we requested the base package.

Atoka Trick

We can spend less credits by not requesting the base package for all the companies in the request (1), and then select one by one - using their ID - the companies that we think are more likely to become our customers and for which we want to download the data we need (2).

(1) GET https://api.atoka.io/v2/companies?ateco=01&emails=*&ageMax=12&token=TOKEN&limit=10  // consumes 0 credits

(2) GET https://api.atoka.io/v2/companies/6da785b3adf2?packages=base,contacts&token=TOKEN  // consumes 1 credit

For detailed information about credits check out our documentation