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 find a company given its vat, you can just query the endpoint companies, with the vat parameter of the base package, with your TOKEN, like this:
GET https://api.atoka.io/v2/companies?packages=base&vat=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.