Use the Company Match API to correct and enrich approximate data

In this tutorial we will show you how to use the Company Match API to find results starting from data that could be incorrect, inaccurate or incomplete (such as a phone number no longer used) and is therefore ideal for verifying the accuracy of your database or updating it with the latest available data in Atoka.

Useful Resources

Let’s start

Let’s imagine, for example, that we have an incorrectly transcribed VAT match, from which you can not go back to the company.

https://api.atoka.io/v2/companies?packages=base&regNumbers=0241890223&token=TOKEN

{
    "meta": {
        "limit": 10,
        "ordering": "atoka",
        "offset": 0,
        "count": 0
    },
    "items": []
}

Using endpoint companies, in fact, no results are returned.

Thanks to API Company Match, we can do a “fuzzy” search that, even from inaccurate or incomplete data, offers a list of results that might match the request. Interrogating the endpoint companies/match we can establish the required precision using the fuzziness parameter. You do not need to enable any package.

https://api.atoka.io/v2/companies/match?regNumbers=0241890223&fuzziness=2&token=TOKEN

{
    "meta": {
        "limit": 10,
        "count": 63
    },
    "items": [
        {
            "id": "f6dde193da86",
            "confidence": 0.8,
            /*omitted*/
        },
        {
            "id": "6da785b3adf2",
            "confidence": 0.8,
            /*omitted*/
        },
        /*omitted*/
    ]
}

The answer is very similar to that of a normal search, with the addition of the confidence value (0-1), which indicates how the result satisfies the search criteria and is used to sort the results. At this point we can add parameters (for example, name) to refine the search and use the minConfidence parameter to reduce the number of results.

https://api.atoka.io/v2/companies/match?packages=base&regNumbers=0241890223&name=spaziodati&minConfidence=0.8&fuzziness=2&token=TOKEN

{
    "meta": {
        "limit": 10,
        "count": 66
    },
    "items": [
        {
            "id": "f6dde193da86",
            "confidence": 0.8212,
            "name": "SPAZIODATI S.R.L.",
            /*omitted*/
            "base": { /*omitted*/ }
        }
    ]
}

By adding the base package we get more data on the company, allowing us to verify that the returned business is actually the one that is being sought. All packages available for endpoint companies can also be used with the Company Match API.

Relevant Parameters

It is important to note that the purpose of the Company Match API is not to find a set of companies that meet certain requirements, but rather to identify a company from the data at its disposal. For this reason, at least one relevant parameter must be provided to identify a specific company. If no one is used at least one will be returned an error.

https://api.atoka.io/v2/companies/match?municipalities=trento&token=TOKEN

{
    "error": true,
    "message": "No relevant filters provided",
    "statuscode": 400
}

Some examples of relevant parameters are name, regNumbers, emails; The full list, along with all the information about the Company Match API, is available in the documentation.

How much does it cost?

As for the Company Search, the Company Match API consumes 1 credit (companies:*) for each company in the results that has at least one data package. You can avoid consuming credits by removing the packages parameter in the match request, and ask in a separate request the data only of the company you are interested in:

// costs 0 credits
https://api.atoka.io/v2/companies/match?regNumbers=0241890223&fuzziness=2&token=TOKEN

// costs 1 credito companies:*
https://api.atoka.io/v2/companies/f6dde193da86?token=TOKEN&packages=base