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}/
Updated almost 3 years ago