Company lists

Company lists

Company lists are lists of companies that are saved at Vainu. The difference between customer data and company lists is that the company list consists only of companies, and no additional data can be attached to listed companies.

Vainu considers company lists to be either static or dynamic by nature. Both types of lists are available from the API, but only static lists can be edited or created from the API.

Static lists are static by nature, which means that only users may add or delete companies on the list. Vainu will not modify these lists in any way. These lists can be accessed and edited both from Vainu API and Vainu platform.

Dynamic lists can be viewed as a set of filters, which means that individual companies can't be added or deleted from a list. Vainu will automatically keep these lists up-to-date based on filters and which companies fulfill these filters. Dynamic list content can be accessed from both Vainu API and Vainu platform. Creating the dynamic lists is only available from the Vainu platform.

List of lists

For the interaction with a Vainu list, you need to know the list id. You can get all the list details from the "/lists/" endpoint. Lists endpoint will return all the lists that the API key has access to. Note that only lists created by the user or shared with the user who generated the API key are visible.

{
  "results": [
    {
      "id": "5e305b7a5c7ef8001673abc3",
      "name": "Bookmarks",
      "is_named_list": true,
      "default": true,
      "owner_email": "[email protected]",
      "added_companies": null
    },
    {
      "id": "5e9d9d1eb3f25e015cb1afc9",
      "name": "List 1",
      "is_named_list": true,
      "default": false,
      "owner_email": "[email protected]",
      "added_companies": null
    }
  ]
}

📘

Obtaining list id from Vainu platform

List id isn't available directly from the Vainu platform but can be picked from the URL when viewing a list. List id is bolded on the following list URL.

app.vainu.io/vainu/prospects/61767bb3211b40ch627631m?q=jhdbe32d

Get list content

All the requests aiming to get companies belonging to a list are made from the Get Companies endpoint. On this endpoint, you can use a "list" parameter with a list id to get companies. All other functionalities and filters are available as in other queries done with companies endpoint.

Create a new list

Only the static lists can be created from the API. For dynamic lists, this task has to be done from the Vainu Platform. Creating static lists is simple, and the only accepted body parameter is the name of the list. Vainu will handle the rest and assign the list to the user to who the API-Key belongs.

Update a list

Update operations for the list, either add companies to the list or replace the companies from the list. Preferred operation is selected in the request body by field name, and available operations are "add_companies" and "replace_companies". List id is placed to the path of the endpoint.

Replacing the companies will delete all the companies from the list and replace these with the companies sent.

Companies to be added are processed with Vainu matcher. Vainu matcher finds the correct entity for each company. All added companies are present in the response, and in case Vainu finds no match, the company will be null. The order of the added companies is the same in the response as in the request made.

The limit for adding companies by single request is 50. More companies can be added with multiple requests. See the following example for the request body.

PUT https://api.vainu.io/api/v2/lists/{list_id}/

{
  "add_companies": [
    {
      "company_name": "vainu software",
      "country": "FI",
      "business_id": "25578642",
      "address": "Eteläesplanadi 12",
      "postal": "00130",
      "city": "Helsinki",
      "domain": "vainu.com"
    },
    {
      "company_name": "doesnt exist",
      "country": "FI"
    }
  ]
}

The request tried to add two companies to the list. The First has sufficient information, and the second is limited. The following example shows the response of the API.

{
  "id": "5e9d9d1eb3f25e015cb1afc9",
  "name": "List 1",
  "is_named_list": true,
  "default": false,
  "owner_email": "[email protected]",
  "added_companies": [
    {
      "country": "FI",
      "company_name": "Vainu. io Software Oy",
      "business_id": "25578642"
    },
    null
  ]
}

As expected, one of the companies was successfully matched, and the other was not, and thus Vainu returned null in its place.

Matching functionality behaves as in Companies endpoint. The most accurate data point for matching is always business_id.

Delete a list

Delete request will delete the list and all the content from the list.