Account API

The Account API provides access to details on a VinTank user’s account, including connected wineries, social activity for brands, social campaigns, social customers, and more. The possibilities for using these entry-points are many, including replicating our social media dashboard within your application/site.

Since these entry-points are accessing a user’s account, you must use OAuth2 for authentication. OAuth2 allows your application to gain secure access to the user’s account without prompting them for their email address and password. All requests below must be made over HTTPS and require the access_token parameter.

Account

URL: https://cruvee.com/v1/account?access_token=…
Method: GET
Version: 1

Returns details on the user and their account (based on the access_token). Note that each VinTank account can have multiple users. So if your system supports multiple users too, you should authenticate each user using OAuth2 and securely store the access_token for each user separately in your data store. You only need to authenticate a user once. Re-authentication will be required when/if your access_token expires. This happens when the user changes their password in VinTank or if they revoke your access token.

Sample Response

{
    "user": {
        "email": "user@email.com",
        "firstName": "Joe",
        "lastName": "User"
    },
    "account": {
        "id": "1380",
        "company": "My Wine Company",
        "businessType": "INDEPENDENT_WINERY"
    }
}

Account Wineries

URL: https://cruvee.com/v1/account/wineries?access_token=…

Returns basic details on each winery connected to the user’s account. Most accounts have just one winery connected but some have multiple (i.e. enterprise wine companies, PR companies, importers, and so on).

Sample Response

{
    "data": [
        {
            "status": "APPROVED",
            "permissions": "READ_ONLY",
            "name": "Jackson Family Wines",
            "ynId": "urn:ynpid:003422",
            "details": "http://apiv1.cruvee.com/wineries/003422.js",
            "defaultRegion": [
                {
                    "name": "United States",
                    "ynId": "urn:ynrid:8400257",
                    "details": "http://apiv1.cruvee.com/regions/8400257.js"
                },
                {
                    "name": "California",
                    "ynId": "urn:ynrid:8400142",
                    "details": "http://apiv1.cruvee.com/regions/8400142.js"
                },
                {
                    "name": "Sonoma Valley",
                    "ynId": "urn:ynrid:8400125",
                    "details": "http://apiv1.cruvee.com/regions/8400125.js"
                }
            ]
        },
        {
            "status": "APPROVED",
            "permissions": "READ_WRITE",
            "name": "Robert Mondavi Winery",
            "ynId": "urn:ynpid:005518",
            "details": "http://apiv1.cruvee.com/wineries/005518.js",
            "defaultRegion": [
                {
                    "name": "United States",
                    "ynId": "urn:ynrid:8400257",
                    "details": "http://apiv1.cruvee.com/regions/8400257.js"
                },
                {
                    "name": "California",
                    "ynId": "urn:ynrid:8400142",
                    "details": "http://apiv1.cruvee.com/regions/8400142.js"
                },
                {
                    "name": "Napa Valley",
                    "ynId": "urn:ynrid:8400075",
                    "details": "http://apiv1.cruvee.com/regions/8400075.js"
                }
            ]
        }
    ]
}

Account Winery Details

URL: https://cruvee.com/v1/account/wineries/{ynId}?access_token=…
Method: GET
Version: 1

Returns details on a single winery connection for an account. The primary differences between what is returned from this entry point vs. the Account Wineries entry point above is the inclusion of brand information for the winery and campaign information for each brand.

Note that most wineries have just one brand but some can have multiple brands. A brand in our data model represents a branded product line for a winery. Therefore, if a winery has primary and secondary labels, it will have two brands in VinTank.

Request Parameters

Name Required? Description
ynId Yes The Winery YnId for a winery connected to this account. You can determine a winery’s YnId from the Account Wineries entry point response above.

Sample Response

{
    "status": "APPROVED",
    "permissions": "READ_WRITE",
    "name": "Robert Mondavi Winery",
    "ynId": "urn:ynpid:005518",
    "details": "http://apiv1.cruvee.com/wineries/005518.js",
    "defaultRegion": [
        {
            "name": "United States",
            "ynId": "urn:ynrid:8400257",
            "details": "http://apiv1.cruvee.com/regions/8400257.js"
        },
        {
            "name": "California",
            "ynId": "urn:ynrid:8400142",
            "details": "http://apiv1.cruvee.com/regions/8400142.js"
        },
        {
            "name": "Napa Valley",
            "ynId": "urn:ynrid:8400075",
            "details": "http://apiv1.cruvee.com/regions/8400075.js"
        }
    ],
    "brands": [
        {
            "name": "Robert Mondavi Private Selection",
            "ynId": "urn:ynbid:00551802",
            "details": "http://apiv1.cruvee.com/brands/00551802.js",
            "defaultRegion": [
                {
                    "name": "United States",
                    "ynId": "urn:ynrid:8400257",
                    "details": "http://apiv1.cruvee.com/regions/8400257.js"
                },
                {
                    "name": "California",
                    "ynId": "urn:ynrid:8400142",
                    "details": "http://apiv1.cruvee.com/regions/8400142.js"
                },
                {
                    "name": "Napa Valley",
                    "ynId": "urn:ynrid:8400075",
                    "details": "http://apiv1.cruvee.com/regions/8400075.js"
                }
            ],
            "campaign": {
                "name": "Robert Mondavi Private Selection",
                "id": "4f142c93e4b0c0899513f969"
            }
        },
        {
            "name": "Robert Mondavi Winery",
            "ynId": "urn:ynbid:00551801",
            "logoURL": "http://assets.cruvee.com/wineries/851b4189d86847349da3eda46b21c8a0_s.jpg",
            "details": "http://apiv1.cruvee.com/brands/00551801.js",
            "defaultRegion": [
                {
                    "name": "United States",
                    "ynId": "urn:ynrid:8400257",
                    "details": "http://apiv1.cruvee.com/regions/8400257.js"
                },
                {
                    "name": "California",
                    "ynId": "urn:ynrid:8400142",
                    "details": "http://apiv1.cruvee.com/regions/8400142.js"
                },
                {
                    "name": "Napa Valley",
                    "ynId": "urn:ynrid:8400075",
                    "details": "http://apiv1.cruvee.com/regions/8400075.js"
                }
            ],
            "campaign": {
                "name": "Robert Mondavi Winery",
                "id": "4ee69b57e4b019bf8b146a09"
            }
        }
    ]
}

Social Media Campaign Details

URL: https://cruvee.com/v1/campaigns/{campaignId}?access_token=…
Method: GET
Version: 1

Returns details for a brand/social campaign. Campaigns in VinTank represent the keywords and filtering rules used by the system to harvest and match social media conversations about a brand or user-defined topic. A brand campaign is specific to a brand while a social campaign is about some topic/concept defined by the user (i.e. like a “saved search”).

You can use this API to replicate the Dashboard displayed within the user’s VinTank account.

Request Parameters

Name Required? Description
campaignId Yes The ID for a brand or social campaign. You can discover the brand/social campaigns for a winery from the Account Winery Detail entry point above.

Sample Response

{
    "name": "Robert Mondavi Winery",
    "id": "4ee69b57e4b019bf8b146a09",
    "winery": {
        "name": "Robert Mondavi Winery",
        "ynId": "urn:ynpid:005518",
        "details": "http://apiv1.cruvee.com/wineries/005518.js",
        "defaultRegion": [
            {
                "name": "United States",
                "ynId": "urn:ynrid:8400257",
                "details": "http://apiv1.cruvee.com/regions/8400257.js"
            },
            {
                "name": "California",
                "ynId": "urn:ynrid:8400142",
                "details": "http://apiv1.cruvee.com/regions/8400142.js"
            },
            {
                "name": "Napa Valley",
                "ynId": "urn:ynrid:8400075",
                "details": "http://apiv1.cruvee.com/regions/8400075.js"
            }
        ]
    },
    "brand": {
        "name": "Robert Mondavi Winery",
        "ynId": "urn:ynbid:00551801",
        "details": "http://apiv1.cruvee.com/brands/00551801.js",
        "logoURL": "http://assets.cruvee.com/wineries/851b4189d86847349da3eda46b21c8a0_s.jpg",
        "defaultRegion": [
            {
                "name": "United States",
                "ynId": "urn:ynrid:8400257",
                "details": "http://apiv1.cruvee.com/regions/8400257.js"
            },
            {
                "name": "California",
                "ynId": "urn:ynrid:8400142",
                "details": "http://apiv1.cruvee.com/regions/8400142.js"
            },
            {
                "name": "Napa Valley",
                "ynId": "urn:ynrid:8400075",
                "details": "http://apiv1.cruvee.com/regions/8400075.js"
            }
        ]
    },
    "analytics": {
        "mentions": {
            "total": 5957,
            "total30Days": 1482,
            "dailyAverage": 46.3125,
            "percentChange": 4.4397464,
            "newForUser": 5957,
            "series": [
                [
                    1332025200000,
                    21
                ],
                [
                    1332111600000,
                    53
                ],
                [
                    1332198000000,
                    79
                ],
                [
                    1332284400000,
                    46
                ],
                [
                    1332370800000,
                    62
                ],
                [
                    1332457200000,
                    33
                ],
                [
                    1332543600000,
                    37
                ],
                [
                    1332630000000,
                    30
                ],
                [
                    1332716400000,
                    59
                ],
                [
                    1332802800000,
                    41
                ],
                [
                    1332889200000,
                    38
                ],
                [
                    1332975600000,
                    65
                ],
                [
                    1333062000000,
                    32
                ],
                [
                    1333148400000,
                    47
                ],
                [
                    1333234800000,
                    25
                ],
                [
                    1333321200000,
                    39
                ],
                [
                    1333407600000,
                    65
                ],
                [
                    1333494000000,
                    49
                ],
                [
                    1333580400000,
                    44
                ],
                [
                    1333666800000,
                    73
                ],
                [
                    1333753200000,
                    36
                ],
                [
                    1333839600000,
                    26
                ],
                [
                    1333926000000,
                    38
                ],
                [
                    1334012400000,
                    59
                ],
                [
                    1334098800000,
                    41
                ],
                [
                    1334185200000,
                    31
                ],
                [
                    1334271600000,
                    63
                ],
                [
                    1334358000000,
                    33
                ],
                [
                    1334444400000,
                    37
                ],
                [
                    1334530800000,
                    34
                ],
                [
                    1334617200000,
                    25
                ],
                [
                    1334703600000,
                    49
                ]
            ]
        },
        "customers": {
            "total": 4009,
            "newForUser": 4009
        },
        "tastingNotes": {
            "total": 2632,
            "totalWithScores": 2321,
            "normalizedAverage": 39.337784
        }
    }
}

Comments are closed.