Atoka API User Reference

v20240416.0917

People Search

The Atoka People API brings the power of Atoka on your clients (persone fisiche) data.

It is designed to allow easy integrations with your legacy applications or to be used as a standalone application. In both cases it will enable a very rich set of uses cases on your customers: segmentation, data cleaning/data quality/data insights, prospecting, synthesis/faceting, relation discovery and much more.

The data we provide includes:

  • Personal record data including date of birth, known addresses, birthplace and more
  • Company directors, with dates and roles on the italian and selected abroad markets, along with historical data. For each company we provide rich informations including scores, revenues, size, sectors, age, addresses, and more. Coverage of about 10M people
  • Share holders, with ratio, type of property, and historical data. Coverage of about 3M people.
  • Negative events, such as protesti pregiudizievoli and procedure concorsuali, with details. Complete coverage
  • Different kinds of scores based on company connections (coverage of about 1M people), negative events, real estate and more (coverage of about 25M people).
  • Real estate owners with kind of ownership, ratio, full data record of the real estate along with coowners, positions, size, category, type and more. Coverage of about 10M people
  • social accounts including facebook and twitter data
  • geographical scores including Istat scores and derived ones. Coverage of about 30M people

A very rich set of filters allows every kind of query enabling infinite use cases in real time, on always up-to-date and verified informations.

The API is able to accept your data, to allow cross-functional queries based on your and Atoka's data. For example find all of your customers who bought a certain product of yours and owns a flat in Tuscany or build automatic systems which customise your products offered prices depending on the potential customer's company relationships, negative events records and real estate scorings.

Keep on reading to discover how the Atoka People API will allow your business grow to its full potential.

We also have a really nice Command Line Interface client to help you send requests to the Atoka People API, check it out!

https://api.atoka.io/v2/people

All requests must be properly authenticated.

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/people"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/people" -d "explain=true" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/people" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/people" -d "explain=true"

Response

By default this API endpoint returns the list of people matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters

  • fields array,
    default is items

    Get just the list of people matched, or the search facets (or both!).

    If you set this to value none, you'll get just the meta object, with count of people matching your search criteria.

    Please notice that if you request the search facets, you need to provide the facetFields parameter as well.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • items
    • facets
    • none

  • facetFields array

    We want to keep our API as fast as possible, but facets are expensive to compute. To avoid slowing things down, you must explicitly state which facets you want when you request them. We want to make your life as simple as possible, though, that's why we support wildcards to be used in here; with them you will be able to have an initial look at the data, and to explicitly specify the facets you need once you start developing your application.

    This field is required when requesting the search facets through the fields parameter

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * Enable all the facets of all the requested packages
    • atokaIndicators.* Enable all the facets of the package "atokaIndicators"
    • atokaIndicators.personCentralityScore.score
    • base.* Enable all the facets of the package "base"
    • base.address.macroregion
    • base.address.municipality
    • base.address.postcode
    • base.address.province
    • base.address.region
    • base.address.stateCode
    • base.birthDate
    • base.birthPlace.macroregion
    • base.birthPlace.municipality
    • base.birthPlace.province
    • base.birthPlace.region
    • base.birthPlace.stateCode
    • base.gender
    • base.residenceAddress.macroregion
    • base.residenceAddress.municipality
    • base.residenceAddress.postcode
    • base.residenceAddress.province
    • base.residenceAddress.region
    • base.residenceAddress.stateCode
    • cervedIndicators.* Enable all the facets of the package "cervedIndicators"
    • cervedIndicators.cgrP15
    • cervedIndicators.cgrP4
    • cervedIndicators.negativities
    • companies.* Enable all the facets of the package "companies"
    • companies.items.atokaIndicators.innovation.categoryScore
    • companies.items.atokaIndicators.innovation.score
    • and other 41 options... (see the whole list)

  • allowExpensive array

    Some fields could expensive to be computed and returned; either they are computationally costly (like calling and external API), or they are charged extra fees, or both. Such fields must be explicitly enabled through this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • cervedIndicators.cgs
curl -G "https://api.atoka.io/v2/people" -d "fields=items,facets" -d "facetFields=base.*" -d "allowExpensive=cervedIndicators.cgs"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "7ce3e8597a64",
"ids": [
"foo",
...
],
"cervedId": 2044622,
"country": "it",
"name": "John Doe",
"obfuscated": false
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/people" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": {
"count": 34,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/people" -d "fields=facets"

Data packages

For each item in search results, by default, we show just the Atoka Person ID (and little more).

By using the packages parameter you can fine tune the results to the level your application actually requires, or show all information available using all the data packages you subscribed to (with packages=*).

Remember: your subscription gives you access to different levels of detail in data returned!

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

Parameters

  • packages array

    Fine tune the results to the level of detail your application actually requires.

    The extraction cost per single person will be multiplied to the number of results in your query (up to offset parameter value).

    To avoid using any package, don't pass this parameter and the results will contain just the Atoka Person ID (and little more).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • atokaIndicators
    • base
    • cervedIndicators
    • companies
    • contacts
    • pep
    • realEstate
    • shares
    • socials
    • * (use all the data packages you have an active subscription for)
curl -G "https://api.atoka.io/v2/people" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"items": [
{
"id": "7ce3e8597a64",
"ids": [
"foo",
...
],
"cervedId": 2044622,
"country": "it",
"name": "John Doe",
"obfuscated": false,
},
...
],
"facets": {
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/people" -d "packages=*"

Ordering & Pagination

To download long lists of results you can paginate returned items using these parameters.

You can also decide the order in which items are returned.

Parameters

  • limit integer,
    default is 10

    This is the number of individual objects that are returned in each page.

    Use a number between 0 and 50.

  • offset integer,
    default is 0

    This offsets the start of each page by the number specified.

    Use a number between 0 and 9950.

  • ordering string,
    default is "relevance"

    Selects the order in which results are returned.

    Choose only one among:

    • birthDate

    • birthDateDesc

    • name

    • surname

    • surnameDesc

    • role Will sort people by their "importance" in a company (works only when filtering on specific companies with the companies parameter)

    • relevance

curl -G "https://api.atoka.io/v2/people" -d "limit=10" -d "offset=30" -d "ordering=amount"

General info

In this section we grouped together many filters that apply on general information of people, such has their given or family name, their gender and age. This is the starting point for trying out the People Search API.

Parameters

  • countries array,
    default is it

    Find people based in the specified countries.

    For the moment the only country covered is Italy (it).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • it
    • * matches for any value

  • ids array

    Search via already known Atoka Person IDs.

    Accepts multiple values, separated with , (comma) char.

  • cervedIds array Private parameter

    Return people with matching Cerved IDs.

    Accepts multiple values, separated with , (comma) char.

  • name string base

    Will lookup provided text in the person full name.

  • emails array Private parameter contacts
     companies

    Search for a person through the email.

    Accepts multiple values, separated with , (comma) char.

  • givenName string base

    Will lookup provided text in the person given name only, compared to the name parameter that will search on the full name.

  • familyName string base

    Will lookup provided text in the person family name only, compared to the name parameter that will search on the full name.

  • gender array base

    Will filter people of the given gender only.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • M
    • F
    • * matches for any value

  • taxIds array base

    Search for people's tax identification number.

    For Italy (countries=it), it uses Codice Fiscale.

    Accepts multiple values, separated with , (comma) char.

  • ageMin integer base

    Match people older than the specified amount of years.

    If you need to exclude all people with unknown birth date, just pass this parameter and set it to zero (ageMin=0).

    Mutually exclusive with birthDateFrom and birthDateTo parameters: they cannot be used together.

    When used with ageMax, if the value of both filters is X, only people born exactly X years ago are returned (with precision of one day).

  • ageMax integer base

    Match people not older than the specified amount of years.

    Also excludes all people for which the birth date is unknown.

    Mutually exclusive with birthDateFrom and birthDateTo parameters: they cannot be used together.

    When used with ageMin, if the value of both filters is X, only people born exactly X years ago are returned (with precision of one day).

  • birthDateFrom string base

    Match people born on or after the given date.

    Mutually exclusive with ageMin and ageMax parameters: they cannot be used together.

  • birthDateTo string base

    Match people born at most on the given date.

    Mutually exclusive with ageMin and ageMax parameters: they cannot be used together.

  • relatedTo array companies
     shares

    Match people which have either a share or a position in the given compan(y|es). This is useful to fetch all the people which you know are related to a company, but you don't know (or don't care) how.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/people" -d "ageMin=6" -d "ageMax=24"

Location

Not many of us are lucky enough to have been given a name which is unique in the world (perhaps Michel de Nostredame is not that common, nowadays, but that's already a corner case). When searching for somebody, a good way to disambiguate between people sharing the same full name is by their place of birth. These filters can be used just for that.

Parameters

  • birthPlaceMacroregions array base

    Match people born in this macro-region.

    Accepts multiple values, separated with , (comma) char.

  • birthPlaceRegions array base

    Match people born in this region. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • birthPlaceProvinces array base

    Match people born in this province. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • birthPlaceMunicipalities array base

    Match people born in this municipality. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • birthPlaceStates array base

    Match people born in this country. Please use an ISO_3166-2 code

    Accepts multiple values, separated with , (comma) char.

  • residenceMacroregions array Private parameter base

    Match people whose (legal) residence is in this macro-region.

    Accepts multiple values, separated with , (comma) char.

  • residenceRegions array Private parameter base

    Match people whose (legal) residence is in this region. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • residenceProvinces array Private parameter base

    Match people whose (legal) residence is in this province. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • residenceMunicipalities array Private parameter base

    Match people whose (legal) residence is in this municipality. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • residencePostcodes array Private parameter base

    Match people whose (legal) residence is in this postcode.

    Accepts multiple values, separated with , (comma) char.

  • residenceStates array Private parameter base

    Match people whose (legal) residence is in this country. Please use an ISO_3166-2 code

    Accepts multiple values, separated with , (comma) char.

  • addressMacroregions array Private parameter base

    Match people whose address is in this macro-region.

    Accepts multiple values, separated with , (comma) char.

  • addressRegions array Private parameter base

    Match people whose address is in this region. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • addressProvinces array Private parameter base

    Match people whose address is in this province. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • addressMunicipalities array Private parameter base

    Match people whose address is in this municipality. You can use the Locations service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • addressPostcodes array Private parameter base

    Match people whose address is in this postcode.

    Accepts multiple values, separated with , (comma) char.

  • addressStates array Private parameter base

    Match people whose address is in this country. Please use an ISO_3166-2 code

    Accepts multiple values, separated with , (comma) char.

  • geoStats array Private parameter base

    Match people whose address census cells match the given statistic data query.

    You can provide multiple filters on many geoStats data, and a person is valid only if it satisfies all the conditions given in input. Each filter should be a valid JSON object following this format:

    {
  "field": "<geo_stats_field_name>",
  "min": <min_value>,
  "max": <max_value>
}

    Only field and one of min or max are mandatory for each filter specified. If you provide a value for min, the API will return the people with that geoStat item value greater or equal to the given value, and similarly the max value will match people with field value smaller or equal to the given value.

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "field": "foo",
    "min": 0.42,
    "max": 0.42
    }

  • showGeoStats boolean Private parameter base

    The field geoStats (in package base) is not provided in the output unless is explicitly requested, because of its size.

    To get the geoStats field in output you can:

    • use the geoStats filter with a valid query
    • use this parameter with value true: it will show the geoStats field for the people in the response (if data is available)
curl -G "https://api.atoka.io/v2/people" -d "geoStats={"field": "residentPopulationTotal", "min": 1000}"

Web activity

With these filters it is possible to match people based on their activity on the web.

Parameters

  • socials array socials

    This filter behaves in two different ways, depending on what is passed to it.

    By passing either linkedin, twitter, facebook, or a comma-separated list of any combination of them, the filter will only return people having at least one of the given social accounts (eg: socials=linkedin will only return people with a known linkedin account; socials=linkedin,facebook will only return people with a known linkedin OR facebook account).

    By passing an URL or a comma-separated list of URLs, the filter will try to search people by the given social account (eg: socials=https://twitter.com/elonmusk will return a person only if it has that specific twitter account associated to them).

    Please notice that social data availability in our system is far from having a full coverage: if you can't find a person through this filter, it doesn't mean we don't have any information about such person; try to filter by official information, such as their full name, their birthplace, or the companies they are related to.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/people" -d "socials=linkedin,twitter"

Indicators

These filters allow you to search by people based on some indicators.

Parameters

  • negativities boolean cervedIndicators

    Match people that have some negative events (Italy only):

  • cgrP4 array Private parameter cervedIndicators

    Match people that have the given cgr P4 score value.

    At the moment these are the labels associated with the values

    • 0.0: ASSENZA DI EVENTI;
    • 1.0: EVENTI TRASCURABILI;
    • 2.0: EVENTI MINIMI;
    • 3.0: EVENTI LIMITATI;
    • 4.0: EVENTI SIGNIFICATIVI;
    • 5.0: EVENTI GRAVI;
    • 6.0: EVENTI GRAVISSIMI.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 0.0
    • 1.0
    • 2.0
    • 3.0
    • 4.0
    • 5.0
    • 6.0

  • cgrP15 array Private parameter cervedIndicators

    Match people that have the given cgr P15 score value.

    At the moment these are the labels associated with the values

    • 1.0: ELEVATA CONSISTENZA IMMOBILIARE;
    • 2.0: AMPIA CONSISTENZA IMMOBILIARE;
    • 3.0: BUONA CONSISTENZA IMMOBILIARE;
    • 4.0: DISCRETA CONSISTENZA IMMOBILIARE;
    • 5.0: MODESTA CONSISTENZA IMMOBILIARE;
    • 6.0: IRRILEVANTE CONSISTENZA IMMOBILIARE.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1.0
    • 2.0
    • 3.0
    • 4.0
    • 5.0
    • 6.0
curl -G "https://api.atoka.io/v2/people"

extended

Parameters 
curl -G "https://api.atoka.io/v2/people"

Positions in Companies

These filters allow to search people based on their positions in companies, whether they have a specific role, how to contact them, and so on.

All these fields operate together, which means that you can combine them to produce complex queries referring to each person's positions in companies. For example, by specifying companies=<some-company-id> and phones=* the API will return all people working in the given company with a known phone number.

Parameters

  • companies array companies

    Match people who have a position in these companies. A list of company IDs must be provided, most likely returned by the Company Search API.

    Accepts multiple values, separated with , (comma) char.

  • companiesCervedIds array Private parameter companies

    Match people who have a position in companies matching these Cerved IDs.

    Accepts multiple values, separated with , (comma) char.

  • companiesCountMin integer companies

    Match people having positions in at least this amount of different companies.

  • companiesCountMax integer companies

    Match people having positions in at most this amount of different companies.

  • cLevels array companies

    Filter people having one of the given C-Level position. When using this filter, please be aware that we are estimating this roles with a combination of white and black magic, and the result may not be 100% correct.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • CEO Chief Executive Officer
    • COO Chief Operating Officer
    • CFO Chief Financial Officer
    • CMO Chief Marketing Officer
    • CIO Chief Information Officer
    • CAO Chief Administrative Officer
    • CTO Chief Technology Officer
    • CHRO Chief Human-resources Offices

  • companiesRoles array companies

    If you need to be more specific than cLevels, you can search by the person role in the company; since this field is not normalized, it may contain any kind of position, and therefore only a fulltext search can be performed on it

    Accepts multiple values, separated with , (comma) char.

  • companiesRolesOfficial string,
    default is "*"     companies

    Filter people having only official or unofficial roles.

    Choose only one among:

    • true
    • false
    • * matches for any value

  • companiesAteco array companies

    Match people having positions in companies with ATECO 2007 activity code starting with provided value (for example: 12.34 matches 12.34.56 and also 12.34.87.90). Mutually exclusive with companiesAtecoExclude parameter: they cannot be used together. You can use the ATECO service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesAtecoExclude array companies

    Exclude people having positions in companies with ATECO activity code starting with provided value (for example: 47.11 will exclude 47.11.01 and also 47.11.55.07).

    Mutually exclusive with companiesAteco parameter: they cannot be used together.

    Accepts multiple values, separated with , (comma) char.

  • companiesEmployeesMin integer companies

    Match people that have positions in companies with number of employees greater than the specified amount.

  • companiesEmployeesMax integer companies

    Match people that have positions in companies with number of employees lower than the specified amount.

  • companiesEmployeesUnknown boolean companies

    Match all people that have positions in companies with known (companiesEmployeesUnknown=false) or unknown (companiesEmployeesUnknown=true) number of employees.

    When set to true and combined with companiesEmployeesMin and/or companiesEmployeesMax, matches people that have positions in companies with number of employees in the specified range OR unknown.

  • companiesInnovationScore array companies

    Match people that have positions in companies within the respective score bracket.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • low
    • medium
    • high
    • top

  • companiesInnovationCategoryScore array companies

    Match people that have positions in companies within the respective score bracket.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • low
    • medium
    • high
    • top

  • companiesLegalForms array companies

    Filter people having positions in companies with this legal form of business (country specific).

    You can use the Legal Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesLegalFormsExclude array companies

    Exclude people having positions in companies with this legal form of business (country specific).

    You can use the Legal Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesMacroregions array companies

    Match people with positions in companies with headquarters in this macro-region.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • nord-ovest
    • nord-est
    • sud
    • centro
    • isole

  • companiesMacroregionsExclude array companies

    Match poeple with no positions in companies with headquarters in this macro-region.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • nord-ovest
    • nord-est
    • sud
    • centro
    • isole

  • companiesRegions array companies

    Match people with positions in companies with headquarters in this region.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesRegionsExclude array companies

    Match people with no positions in companies with headquarters in this region.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesProvinces array companies

    Match people having positions in companies with headquarters in this province.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesProvincesExclude array companies

    Match people having no positions in companies with headquarters in this province.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesMunicipalities array companies

    Match people having positions in companies with headquarters in this municipality.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesMunicipalitiesExclude array companies

    Match people having no positions in companies with headquarters in this municipality.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companiesPostcodes array companies

    Match peple with positions in companies having headquarters in specified postcodes.

    Accepts multiple values, separated with , (comma) char.

  • companiesPostcodesExclude array companies

    Match peple with no positions in companies having headquarters in specified postcodes.

    Accepts multiple values, separated with , (comma) char.

  • companiesRevenueMin number companies

    Match people that have positions in companies with at least this revenue.

    Based on latest officially registered company revenue records.

  • companiesRevenueMax number companies

    Match people that have positions in companies with revenue lower than specified amount.

    Based on latest officially registered company revenue records.

  • companiesRevenueUnknown boolean companies

    Match all companies with known (companiesRevenueUnknown=false) or unknown (companiesRevenueUnknown=true) revenue.

    When set to true and combined with companiesRevenueMin and/or companiesRevenueMax, matches people that have positions in companies with revenue in the specified range OR unknown.

  • companiesWebCentralityScore array companies

    Match people that have positions in companies within the respective score bracket.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • low
    • medium
    • high
    • top

  • companiesWebCentralityCategoryScore array companies

    Match people that have positions in companies within the respective score bracket.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • low
    • medium
    • high
    • top

  • companiesAgeMin integer companies

    Match people with positions in companies older than the specified amount of months (based on value of founded field).

    Mutually exclusive with companiesFoundedFrom and companiesFoundedTo parameters: they cannot be used together.

    When used with companiesAgeMax, if the value of both filters is X, only companies founded exactly X months ago are returned (with precision of one day).

  • companiesAgeMax integer companies

    Match people with positions in companies not older than the specified amount of months (based on value of founded field).

    Also excludes all companies for which the date of establishment is unknown.

    Mutually exclusive with companiesFoundedFrom and companiesFoundedTo parameters: they cannot be used together.

    When used with companiesAgeMin, if the value of both filters is X, only companies founded exactly X months ago are returned (with precision of one day).

  • companiesFoundedFrom string companies

    Match people with positions in companies founded on or after the given date

    Mutually exclusive with companiesAgeMin and companiesAgeMax parameters: they cannot be used together.

  • companiesFoundedTo string companies

    Match people with positions in companies founded on or before the given date

    Mutually exclusive with companiesAgeMin and companiesAgeMax parameters: they cannot be used together.

  • companiesStartup boolean companies

    Match people with positions in companies officially registered as Startup Innovativa.

  • companiesPA boolean companies

    Match people with positions in companies that are a public administration.

  • companiesEcommerce boolean companies

    Match people with positions in companies that use an ecommerce

  • phones array companies

    Match for potential phone numbers found. These phone numbers are related to the company where the person works, and will not be their personal phone number.

    Currently it is possible to filter only for the presence of at least one phone number, in the future it will be possible to filter on the phone type as well.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for presence of at least one phone number

  • pep boolean pep

    Match people that are considered PEP (Politically Exposed Person)

curl -G "https://api.atoka.io/v2/people" -d "companiesCountMin=6" -d "companiesCountMax=24" -d "cLevels=CEO" -d "companiesRoles=amministratore delegato" -d "companiesRolesOfficial=true" -d "companiesAteco=62.09.09" -d "companiesEmployeesMin=10000" -d "companiesEmployeesMax=10000" -d "companiesInnovationScore=medium" -d "companiesInnovationCategoryScore=medium" -d "companiesRevenueMin=50000" -d "companiesWebCentralityScore=medium" -d "companiesWebCentralityCategoryScore=medium" -d "companiesAgeMin=6" -d "companiesAgeMax=24" -d "companiesFoundedTo=2012-02-12" -d "companiesStartup=true" -d "companiesPA=true" -d "companiesEcommerce=true" -d "phones=*"

Shares in Companies

If you want to filter people based on whether they have shares in companies or not, here is where you will find your answers.

All these fields operate together, which means that you can combine them to produce complex queries referring to each person's shares in companies. For example, by specifying sharesOwnedIds=<some-company-id> and sharesOwnedRatioMin=0.1 the API will return all people having a share of at least 10% of the specified company.

Parameters

  • sharesOwnedIds array shares

    Match people who have some shares of these companies. A list of company IDs must be provided, most likely returned by the Company Search API.

    Use * to get only people with shares.

    Accepts multiple values, separated with , (comma) char.

  • sharesOwnedIdsExclude array shares

    Match people who don't have shares of these companies. A list of company IDs must be provided, most likely returned by the Company Search API.

    Use * to get all people that has no share in any company

    Accepts multiple values, separated with , (comma) char.

  • sharesOwnedCervedIds array Private parameter shares

    Match people who have some shares of companies matching these Cerved IDs.

    Accepts multiple values, separated with , (comma) char.

  • sharesOwnedRatioMin number shares

    Match people having at least this ratio of shares.

  • sharesOwnedRatioMax number shares

    Match people having at most this ratio of shares.

  • sharesOwnedAmountMin integer shares

    Match people having at least this amount of value of shares.

  • sharesOwnedAmountMax integer shares

    Match people having at most this amount of value of shares.

  • sharesOwnedTypesOfRight array shares

    Match people having this type of right of shares.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • proprietà
    • proprietà non dichiarata
    • usufrutto (estinzione)
    • usufrutto (modificazione)
    • usufrutto
    • intestazione fiduciaria
    • intestazione fiduciaria (estinzione)
    • intestazione fiduciaria (modificazione)
    • trustee
    • gestione del risparmio
    • prestatario
    • diritto di voto
    • prestatore
    • intestazione per conto terzi
    • fondi
    • riportatore
    • riportato
    • gestione discrezionale del risparmio
    • gestione non discrezionale del risparmio
    • deposito
    • delega

  • beneficialOwnerOfIds array shares

    Match people who are beneficial owner of these companies. A list of company IDs must be provided, most likely returned by the Company Search API.

    Use * to get only people that are beneficial owners of some company.

    Accepts multiple values, separated with , (comma) char.

  • beneficialOwnerOfIdsExclude array shares

    Match people who are not beneficial owners of these companies. A list of company IDs must be provided, most likely returned by the Company Search API.

    Use * to get all people that are not beneficial owner of any company

    Accepts multiple values, separated with , (comma) char.

  • beneficialOwnerOfCervedIds array Private parameter shares

    Match people who are beneficial owners of companies matching these Cerved IDs.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/people" -d "sharesOwnedRatioMin=0.25" -d "sharesOwnedRatioMax=0.75" -d "sharesOwnedAmountMin=10000" -d "sharesOwnedAmountMax=50000" -d "sharesOwnedTypesOfRight=proprietà"

Real Estate

Use these filters to match people based on their real estate possessions.

Parameters

  • realEstate array realEstate

    Match people having real estate of a specific type.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • building
    • plotOfLand
    • * matches for any value

  • realEstateMunicipalities array realestate

    Match people having a real estate in this municipality

    Accepts multiple values, separated with , (comma) char.

  • realEstateProvinces array realestate

    Match people having a real estate in this province

    Accepts multiple values, separated with , (comma) char.

  • realEstateRegions array realestate

    Match people having a real estate in this region

    Accepts multiple values, separated with , (comma) char.

  • realEstateMacroregions array realestate

    Match people having a real estate in this macroregion

    Accepts multiple values, separated with , (comma) char.

  • realEstateAdministrativeSection string realestate

    Match people having a realestate TODO

    Must be used in combination with realEstateMunicipalities, realEstateLayout and realEstateLayout

    The administrative section is available only for buildings

  • realEstateCensusSection string realestate

    Match people having a realestate in the given cadastral census section.

    Must be used in combination with realEstateMunicipalities, realEstateLayout and realEstateLayout

    The census section is available only for plots of land

  • realEstateUrbanSection string realestate

    Match people having a realestate in the given cadastral urban section.

    Must be used in combination with realEstateMunicipalities, realEstateLayout and realEstateLayout

    The urban section is available only for buildings

  • realEstateLayout string realestate

    Match people having a realestate in the given cadastral layout.

    Must be used in combination with realEstateMunicipalities and realEstateLayout

  • realEstateLot string realestate

    Match people having a realestate in the given cadastral lot.

    Must be used in combination with realEstateMunicipalities and realEstateLayout

  • realEstateLotDenominator string realestate

    Match people having a realestate in the given cadastral lot denominator.

    Must be used in combination with realEstateMunicipalities, realEstateLayout and realEstateLayout

    The lot denominator is present only for buildings in provinces of Trieste, Gorizia e some in Udine and Belluno.

  • realEstateSubLot integer realestate

    Match people having a realestate in the given cadastral sublot.

    Must be used in combination with realEstateMunicipalities, realEstateLayout and realEstateLayout

  • realEstateCategory array realestate

    Match people having a real estate with this category code

    You can use the Cadastral Category service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any value
    • A/1
    • A/2
    • A/3
    • A/4
    • A/5
    • A/6
    • A/7
    • A/8
    • A/9
    • A/10
    • A/11
    • B/1
    • B/2
    • B/3
    • B/4
    • B/5
    • B/6
    • B/7
    • B/8
    • C/1
    • C/2
    • C/3
    • C/4
    • C/5
    • C/6
    • C/7
    • D/1
    • D/2
    • D/3
    • and other 29 options... (see the whole list)

  • realEstateClassCode array realestate

    Match people having a real estate with this class code

    You can use the Cadastral Class Code service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • realEstateEstimationMin number Private parameter realestate

    Match people having a real estate with (any: poor, average or optimal) estimation (min or max) greater than the given value.

  • realEstateEstimationMax number Private parameter realestate

    Match people having a real estate with (any: poor, average or optimal) estimation (min or max) smaller than the given value.

  • realEstateEstimationPoorMin number Private parameter realestate

    Match people having a real estate with poor estimation (min or max) greater than the given value.

  • realEstateEstimationPoorMax number Private parameter realestate

    Match people having a real estate with poor estimation (min or max) smaller than the given value.

  • realEstateEstimationAverageMin number Private parameter realestate

    Match people having a real estate with average estimation (min or max) greater than the given value.

  • realEstateEstimationAverageMax number Private parameter realestate

    Match people having a real estate with average estimation (min or max) smaller than the given value.

  • realEstateEstimationOptimalMin number Private parameter realestate

    Match people having a real estate with optimal estimation (min or max) greater than the given value.

  • realEstateEstimationOptimalMax number Private parameter realestate

    Match people having a real estate with optimal estimation (min or max) smaller than the given value.

  • realEstateEntitlement array realestate

    Match people having entitlement of the specified type on a real estate

    Accepts multiple values, separated with , (comma) char.

  • realEstateRatio string realestate

    if "partial", match people having at least one real estate in joint ownership with somebody else, if "full" match people having full ownership of at least one real estate.

    Choose only one among:

    • full
    • partial
curl -G "https://api.atoka.io/v2/people" -d "realEstate=buildings"

customdata

Parameters

  • customData array customData

    Using this parameter you will be able to use your custom data imported in Atoka to filter the database.

    The parameter is a json object with this structure

    • customData (string): string identifier of your custom data collection
    • field (string): name of the field that you want to filter
    • unknown (bool): false will give you all the objects with this field populated (no matter the value), true will filter only the ones without any value
    • includes (list): a list of exact values for this field, can be either strings or numbers depending on the field datatype. The values will be combined using OR operator
    • ranges (list): available only for numeric and date fields. list of ranges, combined in or. Each range is represented as a json object with any of these properties: gt, gte, lt, lte.
    • excludes (list): a list of exact values to exclude for this field, can be either strings or numbers depending on the field datatype. The values will be combined using AND operator

    You can filter on more than one field by repeting the parameter for each filter you want to add. Filters on different fields will be combined in AND.

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "customData": "foo",
    "field": "foo",
    "includes": undefined,
    "excludes": undefined,
    "unknown": false,
    "ranges": [
    {
    "gt": undefined,
    "gte": undefined,
    "lt": undefined,
    "lte": undefined
    },
    ...
    ]
    }
curl -G "https://api.atoka.io/v2/people" -d "customData={"customData": "data_id", "field": "field_name", "includes": ["my_value"]}"

Response

The response of the people

{
"items": [
{
"id": "7ce3e8597a64",
"ids": [
"foo",
...
],
"cervedId": 2044622,
"country": "it",
"name": "John Doe",
"obfuscated": false,
},
...
],
"facets": {
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}

Person Details

Show full details of a person.

By default we show all information available using all the data packages you subscribed to. Use the package parameter to fine tune the output format.

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

https://api.atoka.io/v2/people/{id}

Replace {id} with the Atoka Person ID you want details for (as returned by the [People Search](#people)..

All requests must be properly authenticated.

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/people/{id}"

Data Packages

Differently from the People Search API, by default here in the Person Details API we will return all the information you are allowed to see; this may become expensive, of course.

To avoid getting data you don't need, you can use the packages parameter to fine tune the results to the level your application actually requires; if you want to explicitly get all the data, feel free you use our preferred wildcard: packages=*.

Remember: your subscription gives you access to different levels of detail in data returned!

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

Remember: your subscription gives you access to different levels of detail in data returned!

Parameters

  • packages array,
    default is *

    By using this parameter you can fine tune the results to the level of detail your application actually requires.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • atokaIndicators
    • base
    • cervedIndicators
    • companies
    • contacts
    • pep
    • perimeters
    • realEstate
    • shares
    • socials
    • * use all the data packages you have an active subscription for
curl -G "https://api.atoka.io/v2/people/{id}" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"item": {
"id": "7ce3e8597a64",
"ids": [
"foo",
...
],
"cervedId": 2044622,
"country": "it",
"name": "John Doe",
"obfuscated": false,
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}
curl -G "https://api.atoka.io/v2/people/{id}" -d "packages=*"

response

Parameters

  • allowExpensive array

    Some fields could expensive to be computed and returned; either they are computationally costly (like calling and external API), or they are charged extra fees, or both. Such fields must be explicitly enabled through this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • cervedIndicators.cgs
curl -G "https://api.atoka.io/v2/people/{id}" -d "allowExpensive=cervedIndicators.cgs"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/people/{id}" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/people/{id}" -d "explain=true"

Response

Through the autentication credentials (the token) you are given, we are able to adapt the data available in API responses to your specific needs.

Moreover, depending on your subscription plan, you'll be able to retrieve different levels of details from the API calls.

{
"item": {
"id": "7ce3e8597a64",
"ids": [
"foo",
...
],
"cervedId": 2044622,
"country": "it",
"name": "John Doe",
"obfuscated": false,
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}