Atoka API User Reference

v20241018.0953

Overview

You can dig into several millions of company records and enrich your data with just a few lines of code, thanks to our easy to use API endpoints.

We currently offer these services:

  • Company Search, your starting point when you are trying to understand which are actually the companies you are looking for;
  • Company Details, when you already have identified a company you are interested in, and need to get fine grained details about it;
  • Company Match, when you you need to clean, verify or enrich information about a company you already have some data about.

The typical workflow would be to: first to use the search or the match features to build a list of IDs of companies you need more data about; then ask for the actual details of each one of them to the appropriate endpoint.

But the design of the API allows for more advanced use cases, like getting just a high level overview of records satisfying specific criteria (use fields=facets), or getting useful data straight off your searches (pass the packages parameter).

Status

You can check the operational status of the API on the status dashboard. 

https://api.atoka.io

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

API requests without authentication will also fail. The exposed endpoints are read only, thus you can call them either via GET or via POST requests. For parameters accepting multiple values, you can either:
  • follow the suggested practice to use the parameter just once, and separate different values using the comma (,) char;
  • or you can also pass the same parameter multiple times.

Just note that for values containing commas, you have to enclose each one in double quotes (for example: websitesContent="this, and that","something else").

Data in our API

Are you interested in discovering more details about the available data and where they come from? We prepared a page dedicated to the API Data that is perfect for you.

Authentication

Through your authentication credentials, we can detect your subscription plan and retrieve the proper level of company details to show.

You can also use the data packages parameter to fine tune the kind of information you get back from API calls.

If you have special needs and want to further customize the results, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Do you already have a token?

You can check you token credits from https://credits.atoka.io/

Some section of the api show different results depending also on the user that is doing the request. If your application has multiple users, you can manage them and their permissions through the dedicated Authentication Endpoints.
To properly authenticate the request, the API will require you to send the appUser parameter, that should contain the identifier (inside your application) of the user sending the request.

If your application has no user, you will be able to use all the services offered by the api without the "appUser" parameter.

Parameters

  • token string required

    Use the authentication token you were provided.

  • appUser string

    Use the id for the user of your application

    other parameters

    • $app_id optional

      Old authetication solution. Must be used together with $app_key.

    • $app_key optional

      Old authentication solution. Must be used together with $app_id. 

curl -G "https://api.atoka.io/v2/companies"  -d "token=123"

Credit Billing

Each token has a set of credit buckets, each of them has a different type of credits and could have different duration.

Why different type of credits

The Atoka API offers you various endpoints and each of them provides you a collection of objects of different types, and each collection requires its own type of credit: for companies search/match/details you will need companies credits, for people endpoints you will need people credits etc..

Besides the first-citizen API collections, you will also see in your token credit status a long list of other credit buckets (ateco, admindiv..) that are used by the suggester endpoints.

What the duration is

Each credit bucket has a duration that defines after how much time, starting from the first usage, the credit will be reset. You can check when this will happen for each credit bucket from next reset on credits.atoka.io.

For example, a credit bucket with 1 day duration implies that its content will refill 1 day after the first credit consumed in that bucket. There can also be credit buckets with infinite duration, and this means that they will never be refilled.

How to check credits status

You can check in real time the status of your token from credits.atoka.io

For each request submitted, you can check how many credits it consumed by reading the response header X-Uniapi-Cost, example:

"X-Uniapi-Cost": "units=90.0, companies=10.0, companies:*=10.0"

This means that the request consumed 10 companies credits and 10 companies:* credits.

Note: in this header you will also see unit credits, please ignore them since they are not considered in the token billing.

How many credits each request costs

1 object = 1 credit

The quantity of credits used by each request depends only on the number and type of objects you will get in the response. It doesn't matter if you passed 5 filters, if it was a search or a match request, you will be billed for the number of companies (or location, people ecc..) that you retrieved. Each collection has 3 sub-type of credits, <collection>, <collection>:* and <collection>:facet. Let’s see when we will use each one of them.

No Packages

If you perform a request with no package in the response, you will use only <collection> credits, one for each object in the response. We usually don't make API users pay for <collection> credits, this type of metric is mainly used for rate limiting on data and internal statistics.

Example: consumes 10 companies credits

GET https://api.atoka.io/v2/companies?token=T&name=spazio
X-Uniapi-Cost: companies=10.0

Data Packages

If you get at least one package in the response objects, this will cost you 1 <collection> credit + 1 <collection>:* credit for each object in the response.
To get packages in the response, you should add to the request the parameter packages. The number of packages obtained for each collection object is not important for the billing, what matters is if you got at least a package in the response of a company. This applies regardless of the endpoint, being it search, match, or details.

Example: consumes 10 companies credits and 10 companies:* credits

GET https://api.atoka.io/v2/companies?token=T&municipalities=trento&packages=base
X-Uniapi-Cost: units=90.0, companies=10.0, companies:*=10.0

Example: consumes 10 companies credits and 10 companies:* credits

GET https://api.atoka.io/v2/companies?token=T&municipalities=trento&packages=base,contacts
X-Uniapi-Cost: units=90.0, companies=10.0, companies:*=10.0

Example: consumes 1 companies credit and 1 companies:* credit

GET https://api.atoka.io/v2/companies/6da785b3adf2?token=T&packages=*
X-Uniapi-Cost: units=9.0, companies=1.0, companies:*=1.0

Example: consumes 1 locations credit and 1 locations:* credit

GET https://api.atoka.io/v2/locations?ids=0ef76064b441token=T&packages=base
X-Uniapi-Cost: units=9.0, locations=1.0, locations:*=1.0

Facets

When you ask for facets (using the facetFields parameter), your token will be billed with 1 credit of type <collection>:facets for each facet field in the response.

Example: since this call will give us 2 facets in the response (email and phones), it consumes 2 credits for companies:facets (you can ignore the companies:*:facets count)

GET https://api.atoka.io/v2/companies?token=T&packages=contacts&fields=facets&facetFields=contacts.*
X-Uniapi-Cost: companies:*:facets=2.0, companies:facets=2.0

In the API Tutorials you can check out some examples on how to request only the information you need by using only the strictly necessary credits.

Rate limiting

There is a rate limit on calls to the APIs of 10 requests per second per token. If you exceed the rate limit your request will be denied with a status code of 429. The limit is implemented with a token bucket algorithm, with fill rate 10 req/s and bucket size 1500 to accomodate for bursts of calls.