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.

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.

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

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