With these APIs you can enrich your CRM data with a lot of the information that is already available in Atoka. In particular, in this tutorial we will see how to get company name, ATECO sector, company type, headquarters, revenues, employees, website, email and phone contacts, but the code can easily be adapted to get any API data you have access to.

You will need:

  • VAT number and/or tax code of the companies in your CRM
  • A token to authenticate calls made. If you do not have a token, contact your sales representative. Keep the token as a password: it is unique and non-transferable.

The enrichment process will take place in two steps

  • We will make a call using your VAT number and/or tax code to identify the best match within our systems for your data. The result will be uniquely identified by an Atoka id which you can save in your database to skip this step in future data updates. Important: this call does not consume any credits.
  • With a second call to our API, consuming a credit, we can use the previously obtained Atoka id to download enriched information about the company.

Let’s start!

To search for companies given a VAT number and/or tax code, simply query the companies endpoint with the parameter vat (VAT number), taxIds` (tax code) and your token like this:

GET https://api.atoka.io/v2/companies?vat=02241890223&taxIds=02241890223&token=TOKEN&limit=10

We can also use only one between VAT number and tax code if we do not know both: for example if we only have VAT number we will proceed as this call

GET https://api.atoka.io/v2/companies?vat=02241890223&token=TOKEN&limit=10

The answer, edited for brevity, contains:

  • items: is the list of results (companies) which in this case, by searching for VAT number and/or tax code, has only one element
  • id: is the id that Atoka uses to identify the company
  • meta: contains number of results, sorting, limit and offset. Useful for paging and sorting
{
    "items": [{
        "id": "6da785b3adf2",
        "name": "SPAZIODATI S.R.L.",
        "country": "it",
        "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)"
    }],
    "meta": {
        "count": 1,
        "limit": 1,
        "offset": 0,
        "ordering": "atoka"
    }
}

Now that we have the id of the company in Atoka, we can save it in our CRM for future data updates. By saving it we can avoid making the previous call, unless of course the input data (vat and tax code) is changed.

We now make the call to get all available information about the company:

GET https://api.atoka.io/v2/companies/6da785b3adf2?token=TOKEN
{
    "item": {
        "id": "6da785b3adf2",
        "name": "SPAZIODATI S.R.L.",
        "country": "it",
        "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
        "base": {
            "legalName": "SPAZIODATI S.R.L.",
            "startup": false,
            "taxId": "02241890223",
            "vat": "02241890223",
            "active": true,
            "founded": "2012-02-13",
            "ateco": [{
                "code": "62.01.00",
                "description": "Produzione di software non connesso all'edizione",
                "rootCode": "J"
            }],
            "legalForms": [ ... ],
            "registeredAddress": { ... }
        },
        "web": {
            "description": "SpazioDati works on...",
            "feeds": [ ... ],
            "keywords": [ ... ],
            "languages": [ ... ],
            "logo": " ... ",
            "websites": [{
                "active": true,
                "url": "http://www.spaziodati.eu"
            }, {
                "active": true,
                "url": "http://www.blog.atoka.io"
            }, ... ]
        }
    }
}

As you can see, the data is organised by “packages” (basic, web, …): in the example we only show a few, you can consult here the complete list of packages and the information that each one includes. We have highlighted those that we are interested in displaying in our CRM: the company name, the address, the ATECO code and the website, but obviously all the other fields that you will see in the results can be used for enrichment.

Using the Atoka+ API it is very easy to create a link to Atoka for each company in your CRM or ERP. We recommend you to make it visible and clickable by your users, so that they can reach the Atoka tab of the company with always updated data, with a simple click. To do this simply use the value of the id field obtained from the API and replace it with this Atoka address:

https://atoka.io/it/companies/-/<id>/

For example, using the result of the call illustrated above would result in the following URL:

https://atoka.io/it/companies/-/6da785b3adf2/

But how much does it cost me?

Each company whose data you ask for consumes 1 credit. In the example we see that the first call costs no credit, while the second call costs 1 credit. If you call the API several times, even for the same subject, you will consume 1 credit each time.

What packages are available to me?

Here you can find the complete list of packages and the data they contain. For each package the information that Atoka provides and any applicable filters are indicated, which can be used in a similar way to the tax code example above. The desired packages are requested via the packages parameter. For example

GET https://api.atoka.io/v2/companies?active=true&packages=base,contacts&token=TOKEN&limit=10

It will ask for the base and contacts packages of the top 10 resulting companies. Some packages are made up of nested information and are denoted by a “.” e.g registeredAddress.distance while lists are denoted by “[]” e.g. `ateco[].

Certain data is also marked with the symbol ⚠️ which indicates that access to this data requires an agreement with our data provider and will therefore be automatically excluded from Atoka’s responses if your token is not configured to use it. If you would like to have access to this data you can request it to your sales contact.

The “Base” package

The base package provides a high-level overview of the searched company.

Available fields Description Type of data Available filters
active Is the company active? true / false active
ateco[] Information about the ATECO 2007 code of a company list of objects -
ateco[].code ATECO 2007 code reclassified to more accurately represent the activity of the company (the most specific) string ateco, atecoExclude
ateco[].description A short description of the ATECO 2007 code string -
ateco[].rootCode The class of the ATECO 2007 code string -
cciaa Together with rea is the identifying information provided by the ‘Camera di Commercio’ (this is the REA province code, e.g. “RM” for “Rome”) string regNumbers, ccia
rea Together with cciaa this is the identifying information provided by the Camera di Commercio (REA stands for Repertorio Economico Amministrativo) string regNumbers
When the company was founded yyyy-mm-dd ageMin, ageMax, foundedFrom, foundedTo, age, ageUnknown
gov Is the company a public administration? true / false
govCode Public Administration Identification Code string govCodes
govType The official ISTAT classification (if the company is a PA) string govTypes, govTypesExclude
inGroup Is the company part of a group? true / false -
legalClass Classification of the legal form of the company (e.g. “Corporation”) string legalClasses, legalClassesExclude
legalForms Classification of the legal form of the company (e.g. “corporation”) list of objects -
legalForms[].level The first level corresponds to legalClass, usage of this field is deprecated string -
legalForms[].name Classification of the legal form of the company (e.g. “Corporation”) string legalForms
nace NACE Code (the most specific) list of objects -
nace[].code NACE Code (most specific) string -
nace[].description A short description of the NACE code string -
nace[].rootCode The root of the NACE code string -
noRea Is the company a no rea? true / false noRea
pec[] List of certified electronic mail (CEM) addresses associated with this company string -
registeredAddress.distance The distance of the registered office from the given coordinates number distance
registeredAddress.fullAddress The full address of the registered office string -
registeredAddress.hamlet Village of registered office string -
registeredAddress.lat Latitude of registered office number lat
registeredAddress.latlonPrecision Latitude and longitude precision number -
registeredAddress.lon Longitude of Headquarters number lon
registeredAddress.macroregion The macroregion (e.g. “South”) of the registered office string macroregions, macroregionsExclude, anyAddress
registeredAddress.municipality municipality of registered office string municipalities, municipalitiesExclude, anyAddress
registeredAddress.postcode Postcode of registered office string postcodes, postcodesExclude, anyAddress
registeredAddress.province Province of registered office string provinces, provincesExclude, anyAddress
registeredAddress.provinceCode Province code of the headquarters string -
registeredAddress.region region of headquarters string regions, regionsExclude, anyAddress
registeredAddress.state State of headquarters string -
registeredAddress.streetName Street name of headquarters string -
registeredAddress.streetNumber Street number of the headquarters string -
registeredAddress.toponym Toponym describing the address (e.g. “street”, “square”, ect.) of the headquarters string -
signs The signs that identify a company list of objects signs, signsQuery
signs[].sign The sign that identifies a company string -
startup Is the company a startup? true / false startup
taxId The company’s tax code string taxIds, regNumbers
vat The VAT number of a company string vat, regNumbers

The “Contacts” package

The contacts package provides contact information of the searched company.

Available fields Description Type of data Available filters
emails List of company email addresses list of objects -
emails[].address email address string -
emails[].type Category of the email address "administration", "info", "management", "marketing", "purchases", "sales", "support", "technician", ... emails
emails[].verified The address exists and is able to receive messages true / false -
fax[] List of fax numbers associated with the company list of strings -
phones List of company phone numbers list of objects -
phones[].fullAddress Full address of the location associated with the phone number string -
phones[].locationId Identifier of the location associated with the phone number string -
phones[].number Phone number associated with the company string -
phones[].source The source from which the phone number comes "phone books", "web" -
phones[].verified Has the phone number been cross-checked between different sources or not? true / false -

The “Economics” package

The ’economics’ package provides general economic information about the searched company, such as the balance sheet and the number of employees.

Available fields Description Type of data Available filters
balanceSheets Balance sheets associated with the company list of objects -
balanceSheets[].currency The currency used in the balance sheet string -
balanceSheets[].date The closing date of the balance sheet date -
balanceSheets[].latest Is this the latest available item? true / false -
balanceSheets[].revenue Revenue number revenueMin, revenueMax, revenueUnknown
balanceSheets[].revenueTrend RevenueTrends number revenueTrends
balanceSheets[].year Balance sheet year number -
capitalStock.value The amount of a company’s share capital or stock: more specifically, it includes nominal (or authorised) capital, which is the amount of share capital that the company is authorised by its constitutional documents to issue to shareholders. number -
employees Data about employees associated with the company list of objects -
employees[].date Date relating to the value of employees date -
employees[].latest This is the most recent employee-related data true / false -
employees[].value Total number of employees number employeesMin, employeesMax, employeesUnknown
employees[].year Year of this information number -
public Is the company listed on a stock exchange? true / false -

The “Entities” package

The entities package provides information extracted automatically from various sources and documents such as websites, social profiles, incorporation statements, etc. Each entity is represented by a label and a Wikipedia URL that can be used to get more information (including foreign language translations) via Wikidata or DBpedia.

The entities are also subdivided according to language: de, it, fr, pt and en. Each group of information is provided as a list whose key is the language (e.g. de[].name or fr[].score) and contains the following fields

Available fields Description Type of data Available filters
language Language (de, fr, it ..) object -
language[].name The name of the entity string -
language[].score Probability that this entity is associated with this company number -
`language[].uri Wikipedia/DBpedia Unique URI representing this entity string entities

The “Locations” package

The locations package provides general geographic information about the company and its local locations.

Available fields Description Type of data Available filters
anyAddress.macroregions[] The macroregions (e.g. “South”) in which at least one company site is located string list macroregions, macroregionsExclude, anyAddress
anyAddress.municipalities[] The municipalities in which at least one company location is located string list municipalities, municipalitiesExclude, anyAddress
anyAddress.postcodes[] The postcodes where at least one company location is located string list postcodes, postcodesExclude, anyAddress
anyAddress.provinces[] The provinces where at least one company location is located list of strings provinces, provincesExclude, anyAddress
anyAddress.regions[] The regions where at least one company location is located string list regions, regionsExclude, anyAddress
count The total number of secondary locations (not including the head office of the company) number -
totalCount The total number of locations (including the company’s head office) string -
items List of the top 10 local company locations list of objects -
items[].id Unique location id reusable in all Atoka APIs string -
items[].address.distance The distance of the location from the given coordinates number distance
items[].address.fullAddress Full address string -
items[].address.hamlet Hamlet of local office string -
items[].address.lat Latitude of local office number lat
items[].address.latlonPrecision Local location latitude and longitude precision number -
items[].address.lon Longitude of local location number lon
items[].address.macroregion The macro-region (e.g. “South”) of the local site string -
items[].address.municipality Municipality of the local office string -
items[].address.postcode Postcode of local office string -
items[].address.province Province of local office string -
items[].address.provinceCode Province code of local office string -
items[].address.region Region of local office string regions, regionsExclude, anyAddress
items[].address.state State of local site string -
items[].address.streetName Local office street name string -
items[].address.streetNumber Street number of local office string -
items[].address.toponym Toponym describing the address (e.g. “street”, “square”, ect.) of the local office string -

The “People” package

The people package contains the list of roles held by people or companies within the searched company. Information is provided for at most the first 10 roles in the company.

Available fields Description Type of data Available filters
count Number of persons whose position in the company is known number -
items List of people list of objects -
items[].birthDate Birth date of the person in the position string -
items[].cLevels[] C-level positions are the highest or most senior management positions in a company. For example, a CEO (Chief Executive Officer) has a C-level job string -
items[].emails[].address Email address string -
items[].emails[].verified The email address exists and is able to receive messages true / false -
items[].familyName Last name of the person holding the position string -
items[].gender Gender of person holding position string -
items[].givenName Name of the person holding the position string -
items[].id Atoka ID of the person holding the position string -
items[].name Name of the position held by this person string -
roles[].name Name of the position string -
roles[].since Start date of position date -

The “Shares” package

The shares package contains general information about the company’s holdings.

Available fields Description Type of data Available filters
beneficialOwnerOf List of beneficial owners list of objects -
beneficialOwnerOf[].active Is the beneficial owners active? true / false -
beneficialOwnerOf[].id Atoka ID of the beneficial owner string -
beneficialOwnerOf[].legalName Legal name of the beneficial owner string -
beneficialOwnerOf[].name Name of the beneficial owner string -
beneficialOwners List of beneficial owners list of objects -
beneficialOwners[].active Is the beneficial owner active? (valid if company=true true / false -
beneficialOwners[].company Is the company beneficiary owner a company or a person? true / false -
beneficialOwners[].id Atoka ID of the actual beneficiary string -
beneficialOwners[].legalName Legal name of the beneficial owner (valid if company=true) string -
beneficialOwners[].name Name of the beneficial owner string -
shareholders List of shareholders list of objects -
shareholders[].active Is the shareholder company active? (valid if company=true) true / false -
shareholders[].amount Quantity held number -
shareholders[].company Is the shareholder a company or a person? true / false -
shareholders[].id Atoka ID of the company or person holding the share string -
shareholders[].lastUpdate The last time the position was updated date -
shareholders[].legalName Legal name of the shareholder (valid if company=true) string -
shareholders[].name Name of the beneficial owner string -
shareholders[].ratio Percentage owned number -
shareholders[].typeOfRight The type of rights exercised over the company string -
sharesOwned List of shares owned list of objects -
sharesOwned[].active Is the company whose shares you own active? true / false -
sharesOwned[].amount Value of holdings owned number -
sharesOwned[].id Atoka ID of the company in which you own shares string -
sharesOwned[].lastUpdate The last time the shares owned data was updated. date -
sharesOwned[].legalName Legal name of the company in which you own shares string -
sharesOwned[].name Name of company in which it holds shares string -
sharesOwned[].ratio Percentage owned number -
sharesOwned[].typeOfRight The type of rights exercised over the share string -

The “Web” package

The ‘web’ package contains general information about the company’s internet presence.

Available fields Description Type of data Available filters
description Company description string -
feeds[] RSS feeds related to this company string -
history Company history (if any) string -
keywords[] Keywords that describe the company and its activities. These are words declared by the company itself in the META HTML tag keywords and description string -
languages[] List of languages “spoken” by the company on the web; this information can come either from the website or from social networks or other online resources. Languages are represented by their ISO 639-1 code string -
logo Company logo string -
slogan Company slogan string -
websites List of websites associated with the company list of objects -
websites[].active Is the website active or not? true / false -
websites[].confidence Probability that the web site is associated with the company number -
websites[].url Website URL string websitesDomains
websitesContent[] Relevant parts of the site’s content obtained as a result of searching for text within the website. string websitesContent, websitesContentTag, websitesContentTagStart, websitesContentTagEnd
wikipediaUri The company’s Wikipedia page string -

Useful resources

  • JS Fiddle with the code for the tutorial, the box at the bottom right is working, enter your token, click go…
  • Here you can check the available and consumed credits on your token.

Contact us to try Atoka

More information on Atoka data

Which Data

Numbers, sources, use cases.

Atoka Enterprise API

Big Data at hand.

Enterprise API Tutorial

A quick guide to make the best out of our APIs.

Data Structure

The architecture, sources and contents, example outputs.