Customer data

Save your data at Vainu

Customer data allows you to save and manage your data inside Vainu. Our Customer data endpoints allow CRUD operations for entities you have to bring this information over to Vainu. A typical use case for customer data would be to save companies you have in your CRM to Vainu and easily track changes and events in these companies.

Usually, the Customer data is a good basis for any integration, which needs to either have data from companies you know or these companies need to be accessed from other Vainu products.

Creating customer data objects

Each customer data object consists of three major parts. First, you need to provide matching information that Vainu uses to match your data to the correct company entity. The second part is the matching data Vainu adds to the customer data. The Matching data tells the actual company we matched your data with. Finally, you can deliver additional information to help you access the data or allow your users to filter this data at the Vainu platform.

Following fields can be sent when creating the Customer data object.

Key

Type

Description

last_update

Date

Date when this entity was last updated in your system

lost_deals_count

Integer

Amount of lost deals for the entity in your system

match_data

Object

Object consisting of data you want to use for matching (see example below)

notes

String

Notes as a string

open_deals_count

Integer

Amount of open deals for the entity in your system

owner_email

String

Email of the owner in your system.

unique_id

String

Your own unique id for the entity

won_deals_count

Integer

Amount of won deals for the entity in your system

The Customer data matching allows you to use the company name and business id to match your data against companies in the Vainu database. The Country is recommended to be included in the matching data to prevent mismatches from different countries.

"match_data": {
  "company_name": "Vainu Finland Oy",
  "business_id": "2822996-6",
  "country": "FI"
}

After the matching is completed, Vainu will assign an id, company info, company id and timestamps for the created customer data object.

{
  "owner_email": "[email protected]",
  "origin": "customerDataApi",
  "unique_id": "f39a1a59",
  "won": true,
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "modified": "2020-08-06T12:08:03.220",
  "created": "2020-08-06T12:08:03.219",
  "company_info": {
    "country": "FI",
    "domain": "vainu.com",
    "company_name": "Vainu Finland Oy",
    "vid": 463880794,
    "business_id": "28229966"
  },
  "id": "5f2bf2a35f171f0b0b0041cf",
  "company_vid": 463880794,
  "match_data": {
    "country": "FI",
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6"
  }
}

🚧

Unmatched customer data

Note that Vainu allows you to create customer data objects even though the matching fails. In this case, company_vid will be -1 and company_info null.

Getting customer data objects

You can query Customer data objects with their filter parameters or by getting a single object by id. The filtering mechanism for customer data objects relies on the same logic as getting company data.

Filtering and filter types

You can use filter parameters to get results from specific customer data objects. Most of the filter values are values sent when creating the customer data object. You may combine filter values with filter types to achieve ranges.

Filter

Type

Description

last_update

Date

Last update date sent when customer data object was created or updated

lost_deals_count

Integer

Amount of lost deals saved to customer data object

open_deals_count

Integer

Amount of open deals saved to customer data object

owner_email

String

Owner email saved to customer data object

prospect

Integer

Vainu Id (Vid). Internal Vainu Id of the company

unique_id

String

Unique id saved to customer data object

won

Boolean

Won status saved to customer data object

won_deals_count

Integer

Amount of won deals saved to customer data object

Following filter types may be used with filter parameters (ie. open_deals_count__gte=1)

__gt

Greater than

__gte

Greater than or equal

__lt

Less than

__lte

Less than or equal

__ne

Not equal

Limit and pagination

Limit and pagination are available for more extensive datasets. The default limit for response is 100, which can be increased to 500 with the page_size parameter.

Paging can be achieved with the "page" parameter where the first batch of results is page=1. Following pages can be requested either by increasing page by 1 for each call. The next page is always included in the response, which is null if no new pages are available.

Order

Results can be ordered with the parameter "ordering". Ordering can be applied to filter parameters. Reverse order can be achieved with the - (minus) sign in front of the filter name (i.e. ordering=-lost_deals_count)

GET https://api.vainu.io/api/v2/customer_data/
        ?won_deals_count__gte=1
    &page_size=500
    &page=1
    &ordering=-won_deals_count
    
#Response

{
  "total_results": 1,
  "next_page": "https://api.vainu.io/api/v2/customer_data/?page=2",
  "prev_page": null,
  "results": [
    {
      "won": true,
      "origin": "PublicApi",
      "modified": "2018-06-09T12:30:39.923Z",
      "created": "2018-06-09T12:20:21.341Z",
      "prospect_info": {
        "vid": 463880794,
        "company_name": "Vainu Finland Oy",
        "business_id": "2822996-6",
        "country": "FI",
        "domain": "vainu.io"
      },
      "id": "2b1961522a6e7f19c3e5ac08",
      "prospect": 463880794
    }
  ]
}

Updating company data objects

Update operation for company data object happens with an id issued by Vainu. The request body will be similar to the creation of customer data objects. The id parameter is added to the path of the request.

PATCH https://api.vainu.io/api/v2/customer_data/{id}/

body = {
  "owner_email": "[email protected]",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
}

Deleting customer data objects

You can delete customer data objects with an id issued by Vainu. The id parameter is sent in a path similar to the update request.

DELETE https://api.vainu.io/api/v2/customer_data/{id}/