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:

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:

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:

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.

advertisingTabEnabled

string

When enabled the Brand report will show Advertising data.

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'

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