Atoka API User Reference

Lists Creation

With this API you can create Lists of companies, that you can use later to refine your search, or analyze through the profile API

You can create a list without items and add them later, or create it in one shot with all the companies ids.

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

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your 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/lists"

General info

In this section we grouped together many parameters necessary for the creation of a new list.

Parameters
  • name string required

    list name

  • items array

    list of companies to add to the list

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

  • type string required

    type of items contained in this list

    Choose only one among:

    • company
  • extraData string

    key value object with custom attributes about the list instance

curl -XPOST "https://api.atoka.io/v2/lists" -d "name=lead_list" -d "items=a317c4fdc0af,948fabee720d" -d "type=company" -d "extraData={\"country\": \"italy\"}"

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Parameters
  • token string required

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

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

General info

In this section we grouped together many parameters necessary for searching Lists.

Parameters
  • name string

    Matches list whose name contains the given text

  • types array

    Matches lists containing items of this type

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

    Possible values are:

    • company
  • extraData string

    Matches lists whose extraData field contains the given key/values pairs

curl -G "https://api.atoka.io/v2/lists" -d "name=needle" -d "extraData={\"country\": \"italy\"}"

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

    Selects the order in which results are returned.

    Choose only one among:

    • name
    • modifiedDate
    • modifiedDateDesc
curl -G "https://api.atoka.io/v2/lists" -d "limit=10" -d "offset=30"

Response

The Lists objects

{
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
},
"items": [
{
"id": "string",
"type": "string",
"name": "string",
"version": "string",
"extraData": object
},
...
]
}

List Details

Show full details of a list. This api will not return the items contained in the list but only the metadata attached to the list. If you want to get all the companies in this list, please use the Company Search API combined with the lists filter

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

Replace {id} with the Atoka List ID you want details for.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

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

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": "string",
"type": "string",
"name": "string",
"version": "string",
"extraData": object
},
"meta": {
"add": float,
"remove": float
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
]
}

List Update

With this API you can modify an existing list of companies, changing its metadata and the elements contained

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

Replace {id} with the Atoka List ID you want details for.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

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

General info

In this section we grouped together many parameters necessary for the creation of a new list.

Parameters
  • name string

    list name

  • add array

    list of companies to add to the list

    Note: if you put the same company both in the add and remove param, it will be excluded from the list

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

  • remove array

    list of companies to remove from the list

    Note: if you put the same company both in the add and remove param, it will be excluded from the list

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

  • extraData string

    key value object with custom attributes about the list instance.

    NOTE: the value you send here will completely replace one previously stored. You should always send the whole extra data you want to store

curl -XPUT "https://api.atoka.io/v2/lists/{id}" -d "add=5b0b0b1facd8" -d "remove=d502fba14206" -d "extraData={\"country\": \"italy\"}"

List Delete

With this API you can delete a list.

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

Replace {id} with the Atoka List ID you want details for.

All requests must be properly authenticated.

response

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

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

List Permission

With this API you can see who has permissions associated to a particular list. The response will include all the users that have some permission associated to the list, excluding the owner.

https://api.atoka.io/v2/lists/{id}/permissions

Replace {id} with the Atoka List ID you want to see permission.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

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

pagination

With this API you can see who has permissions associated to a particular list. The response will include all the users that have some permission associated to the list, excluding the owner.

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.

curl -G "https://api.atoka.io/v2/lists/{id}/permissions" -d "limit=10" -d "offset=30"

Response

List of List Permissions Response

{
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
},
"items": [
{
"item": {
"key": "string",
"permission": "string",
"details": {
"read": boolean,
"write": boolean,
"manage": boolean
},
"user": {
"name": "string",
"appUserId": "string"
}
}
},
...
]
}

List Permission - Edit

With this API you can change the access control policies for this list.

The permission is associated directly to the user, using its default share key. With this endpoint you can allow him/her to read, write, share and delete a list. The owner of a list (meaning the user who created the list) does not need any permission in order perform any of the mentioned operation on its lists.

https://api.atoka.io/v2/lists/{id}/permissions/user/{shareUser}

Replace {id} with the Atoka List ID you want details for.

Replace {shareUser} with The user to assign permission for this list.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

curl -XPUT "https://api.atoka.io/v2/lists/{id}/permissions/user/{shareUser}"

General info

In this section we grouped together many parameters necessary for the creation of a new list.

Parameters
  • permission string required

    The permission assigned to the user. Please not that permissions are pyramidal: manage > write > read. read allows the user to view the content of a list write allows the user to change the list (using the List Update endpoint) * delete allows a user to share with somebody else the list (using the List Permission endpoint) and delete the list (using the List Delete endpoint)

    Choose only one among:

    • read
    • write
    • manage
curl -XPUT "https://api.atoka.io/v2/lists/{id}/permissions/user/{shareUser}"

Response

Edit List Permission Response

{
"item": {
"key": "string",
"permission": "string",
"details": {
"read": boolean,
"write": boolean,
"manage": boolean
},
"user": {
"name": "string",
"appUserId": "string"
}
}
}

List Permission - Revoke

With this API you can revoke a permission assigned to an user for a particular list. This API will not delete the user and will delete all the permissions that connect this user to the list.

https://api.atoka.io/v2/lists/{id}/permissions/user/{shareUser}

Replace {id} with the Atoka List ID you want to revoke permission.

Replace {shareUser} with The user to revoke permission for this list.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

curl -XDELETE "https://api.atoka.io/v2/lists/{id}/permissions/user/{shareUser}"

List Permission - Edit (with share keys)

With this API you can change the access control policies for this list.

The permission is associated indirectly to a user through a share key, and can allow him to read, write, share and delete a list. The owner of a list (meaning the user who created the list) does not need any permission in order perform any of the mentioned operation on its lists.

https://api.atoka.io/v2/lists/{id}/permissions/{key}

Replace {id} with the Atoka List ID you want details for.

Replace {key} with The share key to assign permission for this list.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

curl -XPUT "https://api.atoka.io/v2/lists/{id}/permissions/{key}"

General info

In this section we grouped together many parameters necessary for the creation of a new list.

Parameters
  • permission string required

    The permission assigned to the user. Please not that permissions are pyramidal: manage > write > read. read allows the user to view the content of a list write allows the user to change the list (using the List Update endpoint) * delete allows a user to share with somebody else the list (using the List Permission endpoint) and delete the list (using the List Delete endpoint)

    Choose only one among:

    • read
    • write
    • manage
curl -XPUT "https://api.atoka.io/v2/lists/{id}/permissions/{key}"

Response

Edit List Permission Response

{
"item": {
"key": "string",
"permission": "string",
"details": {
"read": boolean,
"write": boolean,
"manage": boolean
},
"user": {
"name": "string",
"appUserId": "string"
}
}
}

List Permission - Revoke (with share keys)

With this API you can revoke a permission assigned to a share key for a particular list. This API will not delete the share key and will not remove other permission for other lists.

https://api.atoka.io/v2/lists/{id}/permissions/{key}

Replace {id} with the Atoka List ID you want to revoke permission.

Replace {key} with The share key to revoke permission for this list.

All requests must be properly authenticated.

Authorization

All API endpoint requires to authorize each request in order to fulfill it.

Using these parameters, you'll be able to authorize your request.

Parameters
  • token string required

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

curl -XDELETE "https://api.atoka.io/v2/lists/{id}/permissions/{key}"