Atoka API User Reference

v20230908.1431
With these APIs you will be able to create a your custom data structure, upload your data that will be available for you to query together with all the information present in the Atoka API. Here is the process that you should follow:
  1. First thing you should create your collection and the schema of your data, using the Custom Data Creation endpoint.
  2. Prepare the file to upload:
    • cannot exceed the size of 1MB (including headers for the request, if you keep the file ~900KB it's fine)
    • CSV file with , as field separator and ; as separator of multiple values in the same field
    • 1 header line, containig the two mandatory columns key and atokaId followed by the field ids of the collection
    • each row should have as first columns key which is an unique identifier and atokaId the atoka Id of the company referring to the row data
    • following the two mandatory columns, there should be the row values in the same order as the header
    Example: 
        key,atokaId,field_1,field_2
    1,6da785b3adf2,val_1A;val_1B,val_2
  3. If you already have an existing collection, maybe you would like to:
    1. perform and incremental update, add data to new companies, or update existing ones, without rewriting the whole thing. In this case you can jump directly to step 4.
    2. replace all the data you uploaded previously, using the same schema. In this case you need to "increase" your custom data version, using the Custom Data Version Increase API. The old version containing the previous data will be the one "active" until you complete the data upload, ensuring no downtime on the user side.
    3. change the schema of your data. You will need to create a new version of the schema with the Custom Data Version Create API and specifying the new list of fields. The old version containing the previous data will be the one "active" until you complete the data upload, ensuring no downtime on the user side.
  4. Upload the file with Custom Data Bulk Upload: it will automatically upload the data using the latest versione available. The custom data writing in asynchronous, because the request will upload the file, start a new task, and return the response. When the data writing is completed the system automatically changes the "active" version of the data to the new one.
  5. If your data is bigger than the maximum allowed size for upload, you can split it in mulitple files, using the same structure, and just call multiple times the Custom Data Bulk Upload API with the different files.
  6. You can check the custom data status using a dedicate API. The writing is completed when a collection is in the status SYNC.
  7. You can check which version of your data is currenlty the "active" one using the Custom Data Version API.

Custom Data List

This API shows you the list of all the custom data collections you have access to, including the list of their fields.

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

All requests must be properly authenticated.

general

Parameters

  • type string

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • country string,
    default is "it"

    the country of companies in the collection

  • showHidden boolean,
    default is false

    Should the API also return data for hidden collections?

curl -G "https://api.atoka.io/v2/customdata" -d "type=company" -d "country=it"

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/customdata"

Response

The custom data schema list

{
"items": [
{
"id": "foo",
"label": "foo",
"type": "foo",
"version": "foo",
"light": false,
"uid": "foo",
"country": "foo",
"hidden": false,
"fields": [
{
"field": "foo",
"esField": "foo",
"label": "foo",
"definition": {
"required": false,
"type": "boolean",
"items": {
"type": "boolean"
},
"options": {
"min": 0.42,
"max": 0.42,
"distribution": {
"numBuckets": 42,
"interval": 0.42,
"ranges": [
{
"from": 0.42,
"to": 0.42
},
...
]
},
"symbols": [
"foo",
...
],
"suggester": undefined,
"ignoreCase": false,
"language": "foo",
"format": "url",
"labelTemplate": "foo",
"urlTemplate": "foo"
}
},
"search": {
"active": false
},
"facet": {
"active": false,
"type": "presence"
}
},
...
]
},
...
],
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Creation

This API allows you to create a new custom data collection.

Structure of the Fields

In order to create a field for your custom data, you have to follow a specific schema (you can find the complete json structure of the fields in the parameter definition)

Each field should have:

  • field: the unique identifier (in the collection) of the field, this is the name you will use also as header in the bulk upload
  • definition: this is the most important part where you define how your data is structure and have this properties:
    • type: the datatype, must be one of: boolean, integer, float, date, time, keyword, text, array. If it is an array you should also add a property "items": {"type": "<datatype>"} that specifies the datatype for the array elements.
    • required: (bool) is this field required for every instance of custom data uploaded?
    • options: an object containing various settings that depends on the datatype, some of them does not apply to all the datatypes.
      • min and max: (for numeric and date-time fields) defines min and max values allowed for the field
      • symbols: (for keyword) list of possible values
      • suggester: (bool, for keyword), does this field support a suggester API?
      • ignoreCase: (bool, for keyword)
      • language: (italian, english, only for text)
      • distribution: (for numeric and date-time fields) defines how the statistics distribution aggregation should be permed on this field.
    • search: is this field searchable? if yes, set it to {"active": true"}
    • facet: is faceting active on this field? if yes set it to {"active": true", "type": "values/presence"}. Use values if you want the counts for each value of the field, or presence if you are interested only in knowning how many companies have a value for this field
https://api.atoka.io/v2/customdata

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • id string required

    the Custom Collection ID you want details for.

  • label string

    Display name for the collection

  • fields array

    The schema fields. Pass this parameter once per field.

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "field": "foo",
    "esField": "foo",
    "label": "foo",
    "definition": {
    "required": false,
    "type": "boolean",
    "items": {
    "type": "boolean"
    },
    "options": {
    "min": 0.42,
    "max": 0.42,
    "distribution": {
    "numBuckets": 42,
    "interval": 0.42,
    "ranges": [
    {
    "from": 0.42,
    "to": 0.42
    },
    ...
    ]
    },
    "symbols": [
    "foo",
    ...
    ],
    "suggester": undefined,
    "ignoreCase": false,
    "language": "foo",
    "format": "url",
    "labelTemplate": "foo",
    "urlTemplate": "foo"
    }
    },
    "search": {
    "active": false
    },
    "facet": {
    "active": false,
    "type": "presence"
    }
    }

  • light boolean,
    default is false

    Is the collection schema light?

  • country string,
    default is "it"

    the country of companies in the collection

curl -XPOST "https://api.atoka.io/v2/customdata" -d "type=company" -d "id=1" -d "country=it"

Authentication

Parameters

  • token string required

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

curl -XPOST "https://api.atoka.io/v2/customdata"

Response

The created object

{
"item": {
"id": "foo",
"label": "foo",
"type": "foo",
"version": "foo",
"light": false,
"uid": "foo",
"country": "foo",
"hidden": false,
"fields": [
{
"field": "foo",
"esField": "foo",
"label": "foo",
"definition": {
"required": false,
"type": "boolean",
"items": {
"type": "boolean"
},
"options": {
"min": 0.42,
"max": 0.42,
"distribution": {
"numBuckets": 42,
"interval": 0.42,
"ranges": [
{
"from": 0.42,
"to": 0.42
},
...
]
},
"symbols": [
"foo",
...
],
"suggester": undefined,
"ignoreCase": false,
"language": "foo",
"format": "url",
"labelTemplate": "foo",
"urlTemplate": "foo"
}
},
"search": {
"active": false
},
"facet": {
"active": false,
"type": "presence"
}
},
...
]
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Read

This API allows you to read the schema of a single custom data collection.

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

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • showHidden boolean,
    default is false

    Should the API also return data for hidden collections?

curl -G "https://api.atoka.io/v2/customdata/{id}" -d "type=company"

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/customdata/{id}"

Response

The custom data schema definition

{
"item": {
"id": "foo",
"label": "foo",
"type": "foo",
"version": "foo",
"light": false,
"uid": "foo",
"country": "foo",
"hidden": false,
"fields": [
{
"field": "foo",
"esField": "foo",
"label": "foo",
"definition": {
"required": false,
"type": "boolean",
"items": {
"type": "boolean"
},
"options": {
"min": 0.42,
"max": 0.42,
"distribution": {
"numBuckets": 42,
"interval": 0.42,
"ranges": [
{
"from": 0.42,
"to": 0.42
},
...
]
},
"symbols": [
"foo",
...
],
"suggester": undefined,
"ignoreCase": false,
"language": "foo",
"format": "url",
"labelTemplate": "foo",
"urlTemplate": "foo"
}
},
"search": {
"active": false
},
"facet": {
"active": false,
"type": "presence"
}
},
...
]
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Update

This API allows you to change the active schema version for a custom data collection.

In the process of uploading your custom data, you should not need to use this API, while it is very useful where there are problems with the most recent data and you need to switch back to another previous version.

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

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • version string Private parameter

    The schema version.

    Use one of the versions that you see are available in the Custom data versions endpoint

  • versionUnset boolean Private parameter

    If set to true, unsets the currently active schema version. Can't be used together with version.

  • label string

    the display name of the collection

  • restore boolean Private parameter

    If set to true, restores a collection that was soft-deleted Can't be used together with any other parameter.

curl -XPUT "https://api.atoka.io/v2/customdata/{id}" -d "type=company" -d "version=mydata_1" -d "versionUnset=true" -d "label=Display Name" -d "restore=true"

Authentication

Parameters

  • token string required

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

curl -XPUT "https://api.atoka.io/v2/customdata/{id}"

Response

The custom data schema definition

{
"item": {
"id": "foo",
"label": "foo",
"type": "foo",
"version": "foo",
"light": false,
"uid": "foo",
"country": "foo",
"hidden": false,
"fields": [
{
"field": "foo",
"esField": "foo",
"label": "foo",
"definition": {
"required": false,
"type": "boolean",
"items": {
"type": "boolean"
},
"options": {
"min": 0.42,
"max": 0.42,
"distribution": {
"numBuckets": 42,
"interval": 0.42,
"ranges": [
{
"from": 0.42,
"to": 0.42
},
...
]
},
"symbols": [
"foo",
...
],
"suggester": undefined,
"ignoreCase": false,
"language": "foo",
"format": "url",
"labelTemplate": "foo",
"urlTemplate": "foo"
}
},
"search": {
"active": false
},
"facet": {
"active": false,
"type": "presence"
}
},
...
]
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Deletion

CAREFUL: This API allows you to delete an existing custom data collection, and all the data uploaded in it. A collection can be deleted only if all its versions are in status deleted.

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

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • hard boolean,
    default is false     Private parameter

    Whether to soft-delete (hide) the collection, or hard-delete (remove from DB) it.

curl -XDELETE "https://api.atoka.io/v2/customdata/{id}" -d "type=company"

Authentication

Parameters

  • token string required

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

curl -XDELETE "https://api.atoka.io/v2/customdata/{id}"

Response

Delete Response

Custom Data Count

This API allows you to count the number of documents in a custom data collection version.

https://api.atoka.io/v2/customdata/{id}/count

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • version string required

    the schema version

curl -G "https://api.atoka.io/v2/customdata/{id}/count" -d "type=company" -d "version=mydata_1"

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/customdata/{id}/count"

Response

counts for that version

{
"item": {
"id": "foo",
"label": "foo",
"type": "foo",
"version": "foo",
"light": false,
"uid": "foo",
"country": "foo",
"hidden": false,
"count": 42
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Version List

This API allows you to get all schema versions available for a custom data collection.

You can recognize the current active one by the field active: true.

https://api.atoka.io/v2/customdata/{id}/versions

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • versionStatus string

    desired status of the Custom Data version

    Choose only one among:

    • new
    • enabled
    • deleted
curl -G "https://api.atoka.io/v2/customdata/{id}/versions" -d "type=company" -d "versionStatus=enabled"

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/customdata/{id}/versions"

Response

The custom data version list

{
"item": {
"id": "foo",
"label": "foo",
"light": false,
"uid": "foo",
"type": "foo",
"hidden": false,
"country": "foo",
"versions": [
{
"active": false,
"fields": [
{
"field": "foo",
"esField": "foo",
"label": "foo",
"definition": {
"required": false,
"type": "boolean",
"items": {
"type": "boolean"
},
"options": {
"min": 0.42,
"max": 0.42,
"distribution": {
"numBuckets": 42,
"interval": 0.42,
"ranges": [
{
"from": 0.42,
"to": 0.42
},
...
]
},
"symbols": [
"foo",
...
],
"suggester": undefined,
"ignoreCase": false,
"language": "foo",
"format": "url",
"labelTemplate": "foo",
"urlTemplate": "foo"
}
},
"search": {
"active": false
},
"facet": {
"active": false,
"type": "presence"
}
},
...
],
"light": false,
"status": "new",
"version": "foo"
},
...
]
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Version Create

This API allows you to create a new schema version for a custom data collection. Remember that this will create a new schema with no data inside, and unless you upload the data using the bulk API or change it using the custom data update, this will not be the "active" version (meaning the one providing the data to the user through the Company Search).

https://api.atoka.io/v2/customdata/{id}/versions

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • version string required

    the schema version

  • fields array required

    The schema fields. Pass this parameter once per field.

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "field": "foo",
    "esField": "foo",
    "label": "foo",
    "definition": {
    "required": false,
    "type": "boolean",
    "items": {
    "type": "boolean"
    },
    "options": {
    "min": 0.42,
    "max": 0.42,
    "distribution": {
    "numBuckets": 42,
    "interval": 0.42,
    "ranges": [
    {
    "from": 0.42,
    "to": 0.42
    },
    ...
    ]
    },
    "symbols": [
    "foo",
    ...
    ],
    "suggester": undefined,
    "ignoreCase": false,
    "language": "foo",
    "format": "url",
    "labelTemplate": "foo",
    "urlTemplate": "foo"
    }
    },
    "search": {
    "active": false
    },
    "facet": {
    "active": false,
    "type": "presence"
    }
    }

  • light boolean,
    default is false

    Is the collection schema light?

curl -XPOST "https://api.atoka.io/v2/customdata/{id}/versions" -d "type=company" -d "version=mydata_1"

Authentication

Parameters

  • token string required

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

curl -XPOST "https://api.atoka.io/v2/customdata/{id}/versions"

Response

The custom data version list with the new version

{
"item": {
"id": "foo",
"label": "foo",
"light": false,
"uid": "foo",
"type": "foo",
"hidden": false,
"country": "foo",
"versions": [
{
"active": false,
"fields": [
{
"field": "foo",
"esField": "foo",
"label": "foo",
"definition": {
"required": false,
"type": "boolean",
"items": {
"type": "boolean"
},
"options": {
"min": 0.42,
"max": 0.42,
"distribution": {
"numBuckets": 42,
"interval": 0.42,
"ranges": [
{
"from": 0.42,
"to": 0.42
},
...
]
},
"symbols": [
"foo",
...
],
"suggester": undefined,
"ignoreCase": false,
"language": "foo",
"format": "url",
"labelTemplate": "foo",
"urlTemplate": "foo"
}
},
"search": {
"active": false
},
"facet": {
"active": false,
"type": "presence"
}
},
...
],
"light": false,
"status": "new",
"version": "foo"
},
...
]
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Custom Data Upload Status

With this API you can monitor the status of your custom data upload task.

Possible status are (in order):

  • QUEUED: the task has been created, and is waiting to be exectuted
  • MATCHING: the task started the process of matching your data with the ones available in Atoka
  • MATCHING DONE: the task completed the matching part, and is waiting to start the writing
  • WRITING: the task started the actual writing of the data in our storage
  • WRITING DONE: the task completed the writing and is waiting for the custom data version switch.
  • SYNC: the task switched the "active" version to the latest available and the upload is completed.
https://api.atoka.io/v2/customdata/{id}/progress

Replace {id} with the Custom Collection ID you want details for..

All requests must be properly authenticated.

general

Parameters

  • type string,
    default is "company"

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • version string Private parameter

    The schema version.

    Use one of the versions that you see are available in the Custom data versions endpoint

curl -G "https://api.atoka.io/v2/customdata/{id}/progress" -d "type=company" -d "version=mydata_1"

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/customdata/{id}/progress"

Response

The custom data collection upload status

{
"items": [
{
"id": "foo",
"collection": "foo",
"type": "foo",
"label": "foo",
"version": "foo",
"light": false,
"uid": "foo",
"country": "foo",
"status": "foo",
"uploadType": "foo",
"totalItems": 0.42,
"lag": 0.42,
"started": "foo",
"ended": "foo"
},
...
]
}

Custom Data Text Suggester

This API allows you to get possibile values of a text field in your custom collection.

https://api.atoka.io/v2/customdata/{id}/suggester/{field}

Replace {id} with the Custom Collection ID you want details for..

Replace {field} with the field you want to get possible values.

All requests must be properly authenticated.

general

Parameters

  • type string

    Type of the objects the Custom Data refers to.

    Choose only one among:

    • company
    • person

  • query string required

    Query for the value

curl -G "https://api.atoka.io/v2/customdata/{id}/suggester/{field}" -d "type=company"

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/customdata/{id}/suggester/{field}"

Response

The list of possible values

{
"items": [
{
"id": "foo"
},
...
]
}