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
responseTime
version
requestId
message
deprecationWarnings
data
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.
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
nextUrl
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
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
numberFoundAccuracy
totalResults
will only be an estimation.
This is only supported by certain endpoints and may not be present.
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.
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 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 https://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
messageId
version
data
block.
publishedDateTime
data
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.
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 https://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 https://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.
This endpoint is used for the management of Listing Distribution orders
This endpoint will be sunset once market integration is complete.
This end-point is used to make a one off listing distribution purchase for an account group. It will make a renewal automatically when called the second time for an account group.
Note: This Endpoint is now available to partners selling the Listing Distribution addon in the Vendasta Marketplace. If a partner has monthly Listing Distribution available, activate monthly LD. If not, activate yearly LD.
POST https://partner-central-api.vendasta.com/api/v2/listingDistribution/purchase/
Parameter | Required? | Type | Multiples? | Notes |
---|---|---|---|---|
accountGroupId
|
string
|
A unique account identifier. One and only one of accountGroupId or customerIdentifier must be specified. | ||
customerIdentifier
|
string
|
A unique string identifying the entity or resource. One and only one of accountGroupId or customerIdentifier must be specified. | ||
externalReference
|
string
|
A unique string that is meaningful to identify the purchase. |
Potential status codes
Returns the order information
"data": { "accountGroupId": "AG-123", "externalReference": "order-12345", "fromDate": "2014-03-12", "orderId": "SYN-ABCD1234", "purchaseId": "P-XXXYYYZZZ", "recipients": { "acxiom": { "errors": [], "externalReference": null, "lastSubmittedDateTime": null, "lastSubmittedJobId": null, "name": "acxiom" }, "factual": { "errors": [], "externalReference": null, "lastSubmittedDateTime": null, "lastSubmittedJobId": null, "name": "factual" }, "infogroup": { "errors": [], "externalReference": null, "lastSubmittedDateTime": null, "lastSubmittedJobId": null, "name": "infogroup" }, "localeze": { "errors": [], "externalReference": null, "lastSubmittedDateTime": null, "lastSubmittedJobId": null, "name": "localeze" } }, "thruDate": "2015-03-11" }
Returns nothing for marketplace activations
"data": null
Handler for returning vtax information for partner use, to make things easier for them.
This endpoint returns the full business category taxonomy.
GET https://partner-central-api.vendasta.com/api/v2/vtax/get/
Parameter | Required? | Type | Multiples? | Notes |
---|---|---|---|---|
None |
A list of potential status codes that may be returned
Returns a set of valid Vendasta business category taxonomy in hierarchical fashion. This is three levels deep at most, with children of broader categories being specified by a colon. a third level taxonomy example would be food:chinese:mandarin, for example.
"data": [ { "children": [ { "children": [ { "name": "Wedding Photography", "taxId": "photographers:evenphotography:weddingphotography" } ], "name": "Event Photography", "taxId": "photographers:eventphotography" }, { "name": "Family Photography", "taxId": "photographers:familyphotography" } ], "name": "Photographers", "taxId": "photographers" }, { "name": "Bartenders", "taxId": "bartenders" } ]