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 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
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 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.


Listing Distribution

This endpoint is used for the management of Listing Distribution orders

This endpoint will be sunset once market integration is complete.


Purchase/Renew Listing Distribution v2.1

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 not available to partners selling the Listing Distribution addon in the Vendasta Marketplace

Version 2.1
  • Return 400 if the account group identifier provided is invalid.
Version 2.0
  • Create API for listing distribution purchase.

  • Rate limit: 300/minute
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.
Response codes

Potential status codes

200
Successfully purchased / renewed listing distribution
400
Invalid account group identifier
403
The partner does not have Listing Distribution enabled or the account group does not have a Listing Builder account, or Listing Distribution is available to the partner as an addon in the Marketplace
409
External reference already exists
500
Unknown Error
Example response

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"
}

Vendasta Taxonomy

Handler for returning vtax information for partner use, to make things easier for them.


Vendasta Taxonomy Ids v2.0

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
Response codes

A list of potential status codes that may be returned

200
Successfully loaded and returned the taxonomy.
Example response

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"
    }
]