Get the name and registered office of a company having the VAT ID

In this tutorial we will show you how to use for the first time the Company Search API in order to get the legal name and headquarters address of a company given its VAT.

Useful resources

• API di Company Search documentation (the api that we’ll use)
• JS Fiddle with code for the tutorial, the bottom right box is actually working, just fill in your token and go
• Here you can check how many credits are available and you consumed on your token, and here you can find funrther information about credit billing

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?packages=base&regNumbers=02241890223&token=TOKEN&limit=10

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

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

or just the tax code (taxIds parameter):

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

The answer modified for brevity, contains:

• items: è is the list of results, companies, which in this case, looking for VAT, has only one item
• meta: contains number of results, order, limit and offset. Useful to paginate and order
• id: is the ID that Atoka uses to identify the company, used by many other APIs
• name, fullAddress: the information, we were looking for!
• base: contains all the information provided by the basic package, detail of the address, NACE code, company type, date of foundation and more

{
    "items": [{
        "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",
            "nace": [{
                "code": "62.01",
                "description": "Computer programming activities",
                "rootCode": "J"
            }],
            "legalForms": [ ... ],
            "registeredAddress": { ... }
        },
    }],
    "meta": {
        "count": 1,
        "limit": 1,
        "offset": 0,
        "ordering": "atoka"
    }
}

How much does it cost?

Every company with at least one data package costs 1 credit of type companies:*. The example request will then consume 1 credit, because the API returned only 1 company, and we asked for the package base for it (using package=base in the request).

Atoka Trick

In case we are not interested in all the details present in package base (like NACE), we consume 0 credits by just avoid asking for packages:

GET https://api.atoka.io/v2/companies?ateco=62.01&token=TOKEN&limit=10  // costs 0 credits

{
    "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"
    }
}

For further information about credit billing please read our documentation.