Atoka API User Reference
v20230908.1431- First thing you should create your collection and the schema of your data, using the Custom Data Creation endpoint.
- 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
key,atokaId,field_1,field_2 1,6da785b3adf2,val_1A;val_1B,val_2
- If you already have an existing collection, maybe you would like to:
- 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.
- 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.
- 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.
- 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.
- 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.
- You can check the custom data status using a dedicate API. The writing is completed when a collection is in the status SYNC.
- 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
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
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 uploaddefinition
: 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
andmax
: (for numeric and date-time fields) defines min and max values allowed for the fieldsymbols
: (for keyword) list of possible valuessuggester
: (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 falseIs 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
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.
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
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
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
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.
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
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
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
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 falseIs 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
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 exectutedMATCHING
: the task started the process of matching your data with the ones available in AtokaMATCHING DONE
: the task completed the matching part, and is waiting to start the writingWRITING
: the task started the actual writing of the data in our storageWRITING 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
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.
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