Atoka API User Reference

v20241018.0953
A custom data collection is a set of additional information that can be attached to a set of companies or people available in the Atoka API. For each subject (company or person) you can attach a record composed by several fields. With these APIs you will be able to manage your custom data structure and upload your data that will be available for you to query together with all the information present in the Atoka API.
Basic Concepts
Each collection refers to a single type of subject, either company or person: use the parameter type with these APIs to distinguish between the two. A collection may have several versions which are the "containers" of your data.
Each version has a schema (a list of fields) and you can upload data to a specific version: every record you upload must have the specific schema of the version you are uploading to. A version has one of the following status in this order:
  • new: the version has been created and you can still amend the schema, but you cannot upload data yet
  • enabled: the version is available for data upload and you can't change the schema at this stage
  • deleted: the version is no longer available, you can't upload data neither amend the schema
Notes that you can revert the status of a version (ie you can move from enabled to new), see the Custom Data Version Update API. Additionally, you can't delete records from a version, upload is always append only, but you can overwrite a record by simply re-uploading it, or you can upload a brand new version removing unwanted records from the input.

For each collection
  • there must be only one active version: this is the one that is available through the Atoka API, see Custom Data Update API to set/unset the active version for a custom data. Only versions in status enabled can be set as active
  • there can be up to 3 versions in status enabled: if you need to create more versions, delete the unused ones first
Workflow
Here is the process that you should follow:
  1. First, ask us to create a custom data collection. You'll be given the id of the collection and your token will be granted access to that specific collection. Get in touch with your sales contact for further details.
  2. Create the first version (and the related schema) for your newly created collection, using the Custom Data Version Create API.
  3. Enable the newly created version using the Custom Data Version Update API and then set it as active for your collection, using the Custom Data Update API.
  4. 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
  5. Once you have a valid collection, 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 6.
    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. This will create a new version with the same schema of the latest one.
    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.
  6. Upload the file with Custom Data Upload API: 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.
  7. 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 Upload API with the different files.
  8. You can check the custom data status using a dedicated API. The writing is completed when a collection is in the status SYNC. Also, you can check how many records has been loaded at any given time into a version with the Custom Data Count API.
  9. You can check which version of your data is currently the "active" one using the Custom Data Version List 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 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).

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 structured and have these 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 item in the custom data uploaded?
    • options: an object containing various settings that depend on the datatype, some of them do 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 performed 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 knowing how many companies have a value for this field.
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 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"

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

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

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

  • 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 -XPUT "https://api.atoka.io/v2/customdata/{id}/versions/{version}" -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 -XPUT "https://api.atoka.io/v2/customdata/{id}/versions/{version}"

Response

The updated custom data version

{
"item": {
"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 Deletion

CAREFUL: This API allows you to delete an existing custom data version for good. A version can be deleted only when is alredy in status deleted

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

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

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

Response

Delete Response

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

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

  • dryRun boolean,
    default is false

    Is this a dry run or do you want to really write the data?

  • versionId string

    the schema version.

    This parameter is deprecated. Please use version instead

  • version string Private parameter

    The schema version.

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

  • 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/{id}/bulk" -d "type=company" -d "versionId=mydata_1" -d "version=mydata_1"

Authentication

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

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

Response

The custom data collection uploaded

{
"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"
}
},
...
]
},
"errors": {
"foo": undefined,
"bar": undefined,
"baz": undefined
},
"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"
},
...
]
}