Atoka+ API

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 regNumbers parameter and your token like this:

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

One can also use just the VAT number (vat parameter):

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

or just the tax code (taxIds parameter):

GET https://api.atoka.io/v2/companies?taxIds=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.

Create a link to Atoka in your CRM

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.

The “Contacts” package

The contacts package provides contact information of the searched company.

The “Economics” package

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

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

The “Groups” package

The groups package provides information about the corporate groups a company is part of.

The “Locations” package

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

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.

The “Shares” package

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

The “Socials” package

The socials package provides information about the social network accounts connected to the company.

The “Technologies” package

The ’technologies’ package contains general information about technologies used in the company’s websites or other services.

The “Web” package

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

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.