Overview

All API endpoints require the following query string parameters. These parameters must always be present on the query string, even when using the POST version of the APIs.

Parameter Required? Type Multiples? Notes
apiUser string Provided by Vendasta
apiKey string Provided by Vendasta

All API responses will be a JSON dictionary of the form:

{
      "statusCode": 200,
      "responseTime": 13.12,
      "version": "1.1",
      "requestId": "5289947b00ff0b5f9a70d6c8f70001737e726570636f72652d70726f64000170726f642d312d37393400010139",
      "message": "A human-readable message.", # optional
      "deprecationWarnings": {}, # optional
      "data": {} # the actual API response data
  }
where:
statusCode
Matches the HTTP status code.
responseTime
The server response time in milliseconds.
version
The version of this endpoint.
requestId
A unique request ID that can be used to identify an individual request and report any issues.
message
An optional human-readable message.
deprecationWarnings
An optional dictionary of deprecation warnings, keyed by argument name.
data
The actual data of the API response. May be a simple value, or a list, or a dictionary depending on the particular endpoint.

Note The API responses below indicate the data portion of the response.

Note Where multiple arguments are allowed, use repeated parameter names. E.g., foo=1&foo=2&foo=3.

Note Certain data types require particular serialized forms:

  • datetime has the form 2012-12-13T14:32:41Z
  • date has the form 2012-12-13
  • time has the form 14:32:41Z
  • boolean has the formtrue or false

Important Our APIs only accept a maximum url length of 2,000 characters. If providing a large number of parameters, especially repeated parameters, use the POST form of API to guard against surpassing this limit.


Paged results

For API endpoints denoted as "supports paged results", the response dictionary will have more information:

{
      "statusCode": 200,
      ...,
      "data": ['a', 'b' , 'c'],
      "nextUrl": "https://www.example.com/abc123?page=998877",
      "nextQueryString": "page=998877",
      "totalResults": 213,
      "numberFoundAccuracy": 100
  }
where:
data
Will be a list of results; may be a list of dictionaries.
nextUrl
Use this url to get the next page of results. If there are no more results, this value will be null; depending on the particular endpoint, it is also possible that the nextUrl key does not even appear in the dictionary. In either case, this signifies that there are no further results. Important You must append your apiUser and apiKey to the nextUrl before submitting the request; these values are explictly suppressed for security reasons.
nextQueryString
Simply the query string portion of the above nextUrl for convenience. This is useful if you need to push the paging information to the browser (e.g., for an Ajax-driven "next page" action) but want to protect the hostname.
totalResults
Indicates the total number of results. This is only supported by certain endpoints and may not be present.
numberFoundAccuracy
If the number of results found is higher than this number, totalResults will only be an estimation. This is only supported by certain endpoints and may not be present.


Response codes

Unless otherwise noted, a 200 response code indicates success and a 500 response code indicates a server error. In general, 200-series responses are used to indicate success, 400-series responses are used to indicate client errors, and 500-series responses are used to indicate server errors. 400-series errors often contain a message with a description of the client error.


Versioning

Each endpoint has a version number which consists of a major version and a minor version (e.g., v1.1). As non-breaking changes are introduced, the minor version will increase. Non-breaking changes include items like new optional parameters and new entries in dictionaries. It is important that your implementation be able to handle these sorts of adjustments automatically.

If a breaking change is required, a new endpoint will be created with a new major version number (the major version number is included in the url path itself). When this occurs, the old version will be marked as deprecated, however it will continue to operate. If any formal sunsetting of the old endpoint is planned, this will be communicated to you via announcement and migration time will be allotted.

Note When an endpoint has been marked as deprecated, a deprecationWarnings key will appear in the top-most response dictionary.

Note Version adjustments (major and minor) occur on individual endpoints, not for the entire suite of endpoints.


Webhooks

Webhooks allow our servers to push content to you as soon as possible. To use webhooks, you must build a handler on your server and configure the url of the handler on partners.vendasta.com.

Content will be sent to this url using a POST method. The content of the POST will be a JSON-encoded dictionary, with the following basic format:

{
  "event": "some-event-code",
  "messageId": "cb7beb99090a4f5f8406a43ae9f56d88",
  "version": "1.1",
  "publishedDateTime": "2014-12-13T14:15:16Z",
  "data": {} # the actual webhook content
}
where:
event
The event code of the message. You can configure to only receive particular event codes.
messageId
An identifier that is unique to this message.
version
The version number of the content in the data block.
publishedDateTime
The UTC datetime that the message was published.
data
The actual data of the webhook. May be a simple value, or a list, or a dictionary depending on the particular webhook.

A message will be considered to be successfully delivered if your server returns a status code in the range 200-299. All other responses will be considered failures. If your server returns a 401 or 403, no retries will be attempted, otherwise delivery will be retried. Unless otherwise noted, the retry policy will attempt after 5 seconds, 10 seconds, 20 seconds, 40 seconds, 80 seconds etc. At least one delivery per day will be attempted, however, retries will end 7 days after the delivery was originally attempted.

Note No guarantee is made about the order of the messages, especially when retrying is in effect. Your handler must have enough logic to handle out of order messages as well as the small possibility of duplicate message delivery.


Signed Messages

To prevent malicious attempts from other parties, it is possible for our servers to sign the webhook message using a shared cryptographic signing key. Your signing key can be configured at partners.vendasta.com.

When the signing key is configured, we will compute the signature based on the raw content of the HTTP POST body (not the headers). Make sure that you strip any leading and trailing whitespace before computing the signature; the first character will be "{" and the last character will be "}".

The signing technique follows the HMAC specification defined by RFC-2104, using a SHA1 hash. In Python code, the signing process is performed by the following code:

import hmac
import sha

payload = '' # the body of the HTTP POST
signing_key = '' # the shared cryptographic key configured at partners.vendasta.com
signature = hmac.new(signing_key, payload.strip(), sha.sha).hexdigest()

Once the signature is computed, you can compare it to the signature on the header X-Vendasta-HMAC found in the HTTP POST headers. If your computed signature matches the signature in the header, the message is genuine.


Brand Sources

These end-points are used for managing Brand v2 API


Create Brand v2.0

API endpoint to create a brand with a brand name and vTax category

POST https://brand-analytics-api.vendasta.com/api/v2/brand/create/
Parameter Required? Type Multiples? Notes
brandName string The actual name of the brand.
activatedSources string A list of source ids from Reputation Intelligence as strings.
insightsTabEnabled string When enabled this Brand report will show the Insights tab.
location string The vTax location for white list consideration e.g. CA
locationNameTemplate string If provided, locations will be displayed by filling this template with the business' data. Ex. `{company_name}, {city}, {state}`
mapTabEnabled string When enabled this Brand report will show the Map tab.
marketId string The id of the market this brand belongs to.
reviewsTabEnabled string When enabled this Brand report will show the Reviews tab.
socialTabEnabled string When enabled this Brand report will show the Social tab.
taxId string The vTax category Id
visibilityTabEnabled string When enabled this Brand report will show the Visibility tab.
Response codes
200
The brand was created and the vtax category id was set.
400
'activatedSources must be a list of integers' or 'Must specify activatedSources or taxId only, not both' or 'Must specify either activatedSources or taxId'
Example response
"data": {
    "status": "success"
}

Add Brand Location v2.0

API endpoint to add a node to a Brand hierarchy.

  • Rate limit: 75/minute
POST https://brand-analytics-api.vendasta.com/api/v2/brand/add-location/
Parameter Required? Type Multiples? Notes
accountGroupId string The account id associated to the location
brandName string The actual name of the brand.
locationName string The location name to be added to the brand
regions string An ordered list of regions
Response codes
200
The count of nodes created.
400
The brand already exists
409
The node at path already exists or you have reached the maximum number of nodes.
503
Rate limit exceeded (75 per minute)
Example response
"data": {
    "created": 4
}

Get Activated Sources v2.0

API endpoint to retrieve the list of filtered visibility sources for a Brand

POST https://brand-analytics-api.vendasta.com/api/v2/activatedSources/get/
Parameter Required? Type Multiples? Notes
brandName string The actual name of the brand.
Response codes
200
the list of activated sources
404
The brand does not exist
Example response
"data": {
    "activatedSources": [
        "source1", 
        "source2", 
        "source..."
    ]
}

Set Activated Sources v2.0

API endpoint to set the list of filtered visibility sources for a Brand Optionally a vtax category can be passed. If vtax is passed, do a lookup using core sdk for proper sources to be set in the brand Can only pass either the visibility sources or vtax category. Not both. Raise 400 if both sources and vtax are sent

POST https://brand-analytics-api.vendasta.com/api/v2/activatedSources/set/
Parameter Required? Type Multiples? Notes
brandName string The actual name of the brand.
activatedSources string A list of source ids from Reputation Intelligence as strings.
location string The vTax location for white list consideration e.g. CA
taxId string The vTax category Id
Response codes
200
The list of activated visibility sources was set.
400
'activatedSources must be a list of integers' or 'Must specify activatedSources or taxId only, not both' or 'Must specify either activatedSources or taxId'
404
The brand does not exist
Example response
"data": {
    "status": "success"
}

Set Location Name Template v2.0

API endpoint to set the location name template for a Brand Raise 400 if the template is invalid

POST https://brand-analytics-api.vendasta.com/api/v2/locationNameTemplate/set/
Parameter Required? Type Multiples? Notes
brandName string The actual name of the brand.
locationNameTemplate string If provided, locations will be displayed by filling this template with the business' data. Ex. `{company_name}, {city}, {state}`
Response codes
200
The location name template was set.
400
Template had invalid key
Example response
"data": {
    "status": "success"
}

Brand Hierarchy

These end-points are used for managing Brand hierarchies


Delete Node v2.0

API endpoint to remove a node from a Brand hierarchy.

POST/GET https://brand-analytics-api.vendasta.com/api/v2/node/delete/
Parameter Required? Type Multiples? Notes
path string The address of a tree node.
Response codes
200
The count of nodes deleted.
Example response
"data": {
    "deleted": 9
}

Brand Reports

These end-points are used for getting Brand report Urls


Get Report Url v2.0

Endpoint to get a signed URL for a report

POST https://brand-analytics-api.vendasta.com/api/v2/reportUrl/get/
Parameter Required? Type Multiples? Notes
path string The address of a tree node. Ensure the path is formed properly, is the minimum length and begins with the right pid.
expiry string How long the signed report URL will be valid for (in seconds). Default: 86400
omitSignatureFlag boolean Whether or not to sign the URL and include the signature in the query params. Default: false
Response codes
200
The report URL returned.
400
The brand does not exist.
Example response
"data": {
    "secureUrl": "https://[HOST]/report/?sig=[SIGNATURE]&exp=[EXPIRY]&path=[PATH]", 
    "url": "http://[HOST]/report/?sig=[SIGNATURE]&exp=[EXPIRY]&path=[PATH]"
}

Brand Data

These end-points are used to get Brand data


Get Brand Names v2.0

API endpoint for getting the Brands available for a partner

POST/GET https://brand-analytics-api.vendasta.com/api/v2/brands/get/
Parameter Required? Type Multiples? Notes
detailsFlag boolean Indicates whether to provide details about each brand including the names and paths in both original and url encoded form.
Response codes
200
The list of Brand names returned.
Example response
"data": {
    "brands": [
        "Vendasta Inc", 
        "Your Brand"
    ], 
    "details": [
        {
            "brandName": "Vendasta Inc", 
            "path": "PID2|Vendasta Inc", 
            "urlEncodedBrandName": "Vendasta%20Inc", 
            "urlEncodedPath": "PID2%7CVendasta%2520Inc"
        }, 
        {
            "brandName": "Your Brand", 
            "path": "PID2|Your Brand", 
            "urlEncodedBrandName": "Your%20Brand", 
            "urlEncodedPath": "PID2%7CYour%2520Brand"
        }
    ]
}

Get Tree v2.0

API endpoint for getting the information for a whole tree or a portion thereof

POST/GET https://brand-analytics-api.vendasta.com/api/v2/tree/get/
Parameter Required? Type Multiples? Notes
path string The address of a tree node.
fetchAllChildrenFlag boolean Indicator to fetch all of the children of the tree. Default: false
Response codes
200
The tree data returned.
Example response
"data": {
    "tree": {
        "children": [
            {
                "groupNodes": [
                    "G-123", 
                    "G-456"
                ], 
                "isLocation": false, 
                "name": "California", 
                "path": "PID|ABC|California", 
                "urlEncodedPath": "PID%7CABC%7CCalifornia"
            }, 
            {
                "groupNodes": [
                    "G-123", 
                    "G-456", 
                    "G-789"
                ], 
                "isLocation": false, 
                "name": "Monterey", 
                "path": "PID|ABC|California|Monterey", 
                "urlEncodedPath": "PID%7CABC%7CCalifornia%7CMonterey"
            }, 
            {
                "groupNodes": [
                    "G-123", 
                    "G-456", 
                    "G-789", 
                    "G-897"
                ], 
                "isLocation": true, 
                "name": "Mikes Example Shop", 
                "path": "PID|ABC|California|Monterey|Mikes%20Example%20Shop", 
                "urlEncodedPath": "PID%7CABC%7CCalifornia%7CMonterey%7CMikes%2520Example%2520Shop"
            }
        ], 
        "name": "ABC", 
        "path": "PID|ABC"
    }
}

Get Node Details v2.0

API endpoint for getting details about a node or list of nodes. Limits to retrieving 100 at a time.

POST/GET https://brand-analytics-api.vendasta.com/api/v2/nodeDetails/get/
Parameter Required? Type Multiples? Notes
path string A list of addresses of tree nodes as strings. Maximum 100 addresses.
Response codes
200
The details about nodes returned
400
Bad request. Please see the response body for details.
Example response
"data": {
    "PID|ABC": {
        "accountGroupId": "", 
        "createdDateTime": "2012-12-11T15:21:41Z", 
        "marketId": "MARKET-ID", 
        "path": "PID|ABC", 
        "t": "brand", 
        "updatedDateTime": "2012-12-11T15:21:41Z", 
        "urlEncodedPath": "PID%7CABC"
    }, 
    "PID|ABC|California": {
        "accountGroupId": "", 
        "createdDateTime": "2013-01-13T14:08:16Z", 
        "path": "PID|ABC|California", 
        "t": "region", 
        "updatedDateTime": "2013-01-23T17:31:35Z", 
        "urlEncodedPath": "PID%7CABC%7CCalifornia"
    }, 
    "PID|ABC|California|Monterey|Mikes Example Shop": {
        "accountGroupId": "SOMEAGID1234", 
        "createdDateTime": "2013-01-17T14:08:16Z", 
        "path": "PID|ABC|California|Monterey|Mikes Example Shop", 
        "t": "location", 
        "updatedDateTime": "2013-01-27T17:31:35Z", 
        "urlEncodedPath": "PID%7CABC%7CCalifornia%7CMonterey%7CMikes%2520Example%2520Shop"
    }
}

Deprecated Endpoints

The following endpoints are deprecated. Alternate endpoints should be used because these endpoints will stop being supported in the future.


Brand Hierarchy

These end-points are used for managing Brand hierarchies


Create Node v2.0

DEPRECATED

This endpoint is deprecated. Please use "/api/v2/brand/add-location/"

API endpoint to add a node to a Brand hierarchy.

POST/GET https://brand-analytics-api.vendasta.com/api/v2/node/create/
Parameter Required? Type Multiples? Notes
path string The address of a tree node. The path will be validated for any invalid whitespaces character for each node in the path i.e. Brand, Region, Location
srid string A Reputation Intelligence account id.
Response codes
200
The count of nodes created.
400
The brand already exists
409
The node at path already exists or you have reached the maximum number of nodes.
Example response
"data": {
    "created": 4
}