Atoka API User Reference

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
curl -G "https://api.atoka.io/v2/customdata" -d "type=company"

response

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"

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",
    "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"
    }
    },
    "search": {
    "active": false
    },
    "facet": {
    "active": false,
    "type": "presence"
    }
    }
curl -XPOST "https://api.atoka.io/v2/customdata" -d "type=company" -d "id=1"

response

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"

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
curl -G "https://api.atoka.io/v2/customdata/{id}" -d "type=company"

response

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}"

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

  • label string

    the display name of the collection

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

response

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}"

Custom Data Deletion

CAREFUL: This API allows you to delete an existing custom data collection, and all the data uploaded in it.

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
curl -XDELETE "https://api.atoka.io/v2/customdata/{id}" -d "type=company"

response

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}"

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"

response

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"

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"

response

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"

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",
    "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"
    }
    },
    "search": {
    "active": false
    },
    "facet": {
    "active": false,
    "type": "presence"
    }
    }
curl -XPOST "https://api.atoka.io/v2/customdata/{id}/versions" -d "type=company" -d "version=mydata_1"

response

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"

Custom Data Version Increase

This API is a shortcut for the Custom Data Version Create endpoint, when you want to keep the same structure for your data.

This is the API to call before uploading a new full set of data: it will create a new version of custom data with the same schema of the latest available version for the custom data collection.

Similarly to the Custom Data Version Create it will not set the new version as "active".

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

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
curl -XPOST "https://api.atoka.io/v2/customdata/{id}/versions/increase" -d "type=company"

response

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

Custom Data Version Update

This API allow you to change the status of a version and, if the version is still in status new, change its mapping.

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

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

Replace {version} with the Custom Collection version you want to change..

All requests must be properly authenticated.

general

Parameters
  • fields array

    The schema fields. Pass this parameter once per field.

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "field": "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"
    }
    },
    "search": {
    "active": false
    },
    "facet": {
    "active": false,
    "type": "presence"
    }
    }
  • versionStatus string

    desired status of the Custom Data version

    Choose only one among:

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

response

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

Custom Data Upload

Upload a file containing your custom data in the Atoka API. Your data will be uploaded in the latest available custom data version.

Since the maximum request size allowed is 1MB, in case you need to upload more data, just split them in mulitple files, with the same structure, and call this API multiple times with different files.

The API will return as soon as file upload is completed, while the process of uploading actual data in our system could take longer. This is managed by an asynchornous task: you can check its status using the Custom Data Upload Status API.

The custom data upload should be sent as a multipart/form POST request.

https://api.atoka.io/v2/customdata/bulk/{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
  • file string required

    The CSV file containing the data to upload.

    • The maximum size allowed for the whole request is 1MB, we suggest to keep the file < 900KB.
    • Please use , as field separator and ; for separating multiple values in the same field.
    • The file should always have 1 line for header and 2 columns containing a unique identifier for each row (key) and the Atoka Id (atokaId) of the company described in that row.
    • Following the two mandatory columns, there should be the values of the row following the same order of the header

    Example:

    key,atokaId,field_1,field_2
    1,6da785b3adf2,val_1A;val_1B,val_2
    
curl -XPOST "https://api.atoka.io/v2/customdata/bulk/{id}" -d "type=company"

response

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

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/bulk/progress/{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
curl -G "https://api.atoka.io/v2/customdata/bulk/progress/{id}" -d "type=company"

response

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

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"

response

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}"

Custom Data Configurations List

Get all current custom data collections with their schemas

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

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
  • versionStatus string

    desired status of the Custom Data version

    Choose only one among:

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

response

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