Automatic completion of a company form

In this tutorial we’ll see how to get the company register starting from a VAT number, for example to auto-complete the company information in your CRM.

We’ll see how to retrieve company name, ATECO code, company type, registered office, revenues, employees, web site, email and telephone contacts, but the code can be easily adapted to obtain any other information you have access to from the API.

Resources

  • Documentation of the Company Search API we will be using;
  • The full code (Js Fiddle) the bottom right pane is working, enter your token, click go… et-voilà! The HTML and CSS are not very interesting, only the minimum necessary to get it working. The Javascript code instead calls the API and populates the results.
  • Here you can check the credits available and used on your token, and here you can find detailed information about credits.

Lets’ start

When you click the button, this handler runs:

$('#vai').click(function() {
    let token = $('#token').val(),
        piva = $('#piva').val(),
        url = `https://api.atoka.io/v2/companies?token=${token}`;
    
    $.post(url, {
        vat: piva,
        packages: 'base,economics,contacts,web'
    }).done(displayData);
    
    return false;
});

Tokens and VAT numbers are being read and they generate the URL of the API. Note that the token is entered in the string query and not in the call body.

An AJAX call is made in POST mode, passing the vat and packages parameters. To get the data we need, we will need base, economics, contacts and web. You have to use the POST method to circumvent the CORS security controls.

The result of the call is handled by the displayData function, of which we report an extract:

function displayData(data) {
    let azienda = data.items[0];
    console.log('Atoka data:', azienda);

    $('#ragioneSociale').html(azienda.name);
    $('#sedeLegale').html(azienda.fullAddress);
    $('#ateco').html(
        azienda.base.ateco[0].code + ': ' + 
        azienda.base.ateco[0].description
    );

    // ecc

    if (azienda.contacts.phones) {
        $('#telefono').html(
            azienda.contacts.phones[0].number +
            ' (' + azienda.contacts.phones.length + ' in totale)'
        );
    }
}

… that does nothing but use the JSON to put the various pieces in place.

The result of this endpoint is still an array of items (companies), but since we filter by VAT we can be sure that the result is only one (or no one, if the VAT match does not exist), the first element of the data array data.items[0].

Note the last block with the if: before printing the phone number we verify that azienda.contacts.phones is truthy, that is, present in the object. Also, being phones in an array, we can decide whether to show them all or just the most significant (the first) and simply give them visibility of their total number.

How much does it cost?

Every company with at least one data package costs 1 credit of type companies:*. In the example request we asked for at most 10 companies (default value for the limit parameter), hence potentially every call might consume 10 credits.

Atoka Trick

In this example we always use data from the first company returned from the API call, and ignore the others. In this case, to save credits, we can use the lim limit parameter to obtain only one company in the result, hence consuming at most 1 credit per search.

$('#vai').click(function() {
    let token = $('#token').val(),
        piva = $('#piva').val(),
        url = `https://api.atoka.io/v2/companies?token=${token}`;

    $.post(url, {
        vat: piva,
        packages: 'base,economics,contacts,web',
        limit: 1,
    }).done(displayData);

    return false;
});