Skip to main content

vAnalytics API

This documentation provides Vendasta Partners and Vendors with the ability to send their data to our platform, where it will be used to generate cards for the Executive Report(both single and multi-location), in a new scalable way that supports slicing and rolling up reporting in any way that users need.

You will not need to pre-aggregate your data and insert it into our card templates to be sent weekly or monthly. You can send data as often as you can, and we will aggregate the data for you based on your provided tags.

Data story design​

The most important part of putting analytics into the client-facing reporting, is designing the cards to tell a clear, understandable story. Start by determining what metrics you can share that will be most valuable to someone wanting to know what kind of value, and ROI your product provides to them on a regular basis. Then design your metric cards, and decide exactly what data you need to push to support those cards.

Please mock up what your cards will exactly look like, including any text and labels, using this template of available card styles. Once mocked up, please share these mocks with our team to confirm compatibility with the report, as we will be implementing these cards on our side on your behalf. If you believe that a visualization other than what we have provided would best suit your data, please let us know, and we can evaluate your suggestions for new card types.

Acceptable Card Styles​

Currently, Vendasta developers will implement these cards on our end, once your data is appearing in our database. In the future, we will allow partners to choose and implement these cards themselves, into reporting.

*currently strings are not supported, thus list cards as featured above will come at a later date

API Usage​

Data Submission Frequency​

Depending on the type of data we generally recommend either one data point per day, or creating data points sporadically as they occur.

For example, marketing campaign analytics data (like opens, clicks, and delivered numbers) would likely be submitted as they occur, or summarized daily.

Data Structure​

Data meant for a single purpose, and thus for a single ‘Card’ may be pushed to the vAnalytics API as a BusinessMetric. Different components of the Card are provided as a list of BusinessMetricPoints grouped by an aggregationKey.

Note that the BusinessMetrics are only delivery containers for BusinessMetricPoints. The Cards are built off of aggregated BusinessMetricPoints, and these data points are what matter.

Card Text​

Card information required to be provided to Vendasta:

  1. Label & aggregation keys used in the data design (required)
  2. Short description of card (required)
  3. Longer tooltip description if needed (optional)
  4. Style (required)

Endpoints​

For full details on these endpoints see vAnalytics.

Push Business Metric​

Currently integer values designated by the intval key are the only data type available. This will support most basic card types. strval will be added in upcoming iterations. This means cards such as the List, and CTA won’t be supported in the current release.

For fractions as seen in some of the example cards, submit numerator and denominator as separate points with separate aggregation keys. Specify that this is the case in your submission notes to the Vendasta team.

For decimals, submit them as Accountant integers, and specify in your submission notes to the Vendasta team if we should divide by 10 or 100.

dateHappened format YYYY-MM-DDTHH:MM:SSZ

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "AG-S52RVH8H6H",
    "label": "Campaigns System",
    "points": [
      {
        "dateHappened": "2020-02-05T15:04:05Z",
        "aggregationKey": "opens",
        "intval": "1"
      }
    ]
  }'

Get a business metric point​

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics/point/get' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "8108fc06-f455-4089-b324-f743eac28acc"
  }'

Get a business metric​

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics/get' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "AG-S52RVH8H6H",
    "label": "Campaigns System",
    "dateRange": {
      "startDate": "2020-02-01T15:04:05Z",
      "endDate": "2020-02-10T15:04:05Z"
    },
    "cursor": "",
    "pageSize": "100"
  }'

Delete business metric point​

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics/delete' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "3143a075-701b-4067-9115-6e472f44c30f"
  }'

Delete business metrics points​

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics/delete-multi' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "businessMetrics": [
      {
        "id": "b808aa37-44b1-4678-a54a-0f3d38381887"
      },
      {
        "id": "d2187725-1960-4d74-91a0-e7915ac7c13b"
      },
      {
        "id": "3143a075-701b-4067-9115-6e472f44c30f"
      },
      {
        "id": "3143a075-701b-4067-9115-xxxx"
      }
    ]
  }'

Examples​

Single Number​

A single BusinessMetric

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "AG-XXXXXXXX",
    "label": "Campaigns System",
    "points": [
      {
        "dateHappened": "2021-01-05T15:04:05Z",
        "aggregationKey": "opens",
        "intval": "3"
      },
      {
        "dateHappened": "2021-01-05T15:04:05Z",
        "aggregationKey": "clicks",
        "intval": "4"
      }
    ]
  }'

The same data provided via multiple requests:

Request 1:

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "AG-XXXXXXXX",
    "label": "Campaigns System",
    "points": [
      {
        "dateHappened": "2021-01-05T15:04:05Z",
        "aggregationKey": "opens",
        "intval": "3"
      }
    ]
  }'

Request 2:

curl -X POST 'https://prod.apigateway.co/grpc/v1/business-metrics' \
  -H "Authorization: Bearer <Token with 'business.metrics' scope>" \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "AG-XXXXXXXX",
    "label": "Campaigns System",
    "points": [
      {
        "dateHappened": "2021-01-05T15:04:05Z",
        "aggregationKey": "clicks",
        "intval": "4"
      }
    ]
  }'