Social Marketing Documentation

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.

Account

These endpoints are used for managing accounts within Social Marketing.

Delete account v1.0

Calls Accounts to deactivate account. Account will be deactivated immediately, but billing will continue until the anniversary or commitment date.

Rate limit: 300/minute

POST/GET https://social-marketing-api.vendasta.com/api/v1/account/delete/

Parameter	Required?	Type	Multiples?	Notes
`accountId`		`string`		The Account ID (AC-XXXXXX) of the account to be deleted.

Response codes

200: Account deleted.

Example response

The Account ID will be as supplied.

"data": {
    "accountId": "AC-B0S4N3L3"
}

Retrieve account details v1.0

Retrieve details regarding a given account or accounts by account id or customer id. Multiple id's may be specified, but only account id's or customer id's may be specified on a single request. Response is a dictionary of account objects keyed on either account id or customer id (whichever was sent on the request).

Rate limit: 300/minute

POST/GET https://social-marketing-api.vendasta.com/api/v1/account/details/

Parameter	Required?	Type	Multiples?	Notes
`accountId`		`string`		The account id(s) for which to retrieve details.
`customerIdentifier`		`string`		The customer id(s) for which to retrieve details.

Response codes

200: Account details retrieved.

Example response 1

This response depicts a return based on customerIdentifier.

"data": {
    "COWFARM": {
        "accountGroupId": "AG-123457", 
        "accountId": "AC-B0S4N4L3", 
        "accountOrigin": "ui", 
        "address": "567 1113th Street", 
        "billingCode": "", 
        "city": "Saskatoon", 
        "companyName": "Bushnells Cow Farm", 
        "country": "CAN", 
        "createdDateTime": "2015-01-01 01:00:00Z", 
        "customerIdentifier": "COWFARM", 
        "marketId": "market2", 
        "pid": "DYB", 
        "ssoToken": "COW_TOKEN", 
        "state": "SK", 
        "status": "paid", 
        "taxonomyId": [
            "beautysvc"
        ], 
        "updatedDateTime": "2015-01-01 01:00:00Z", 
        "workNumber": "306-555-0400", 
        "zip": "S7K 5B8"
    }, 
    "HORSEFARM": {
        "accountGroupId": "AG-123456", 
        "accountId": "AC-B0S4N3L3", 
        "accountOrigin": "ui", 
        "address": "567 113th Street", 
        "billingCode": "", 
        "city": "Saskatoon", 
        "companyName": "Bushnells Horse Farm", 
        "country": "CAN", 
        "createdDateTime": "2015-01-01 01:00:00Z", 
        "customerIdentifier": "HORSEFARM", 
        "marketId": "market1", 
        "pid": "DYB", 
        "ssoToken": "HORSE_TOKEN", 
        "state": "SK", 
        "status": "paid", 
        "taxonomyId": [
            "beautysvc"
        ], 
        "updatedDateTime": "2015-01-01 01:00:00Z", 
        "workNumber": "306-555-0409", 
        "zip": "S7K 5B8"
    }
}

Example response 2

This response depicts a return based on accountId.

"data": {
    "AC-B0S4N3L3": {
        "accountGroupId": "AG-123456", 
        "accountId": "AC-B0S4N3L3", 
        "accountOrigin": "ui", 
        "address": "567 113th Street", 
        "billingCode": "", 
        "city": "Saskatoon", 
        "companyName": "Bushnells Horse Farm", 
        "country": "CAN", 
        "createdDateTime": "2015-01-01 01:00:00Z", 
        "customerIdentifier": "HORSEFARM", 
        "marketId": "market1", 
        "pid": "DYB", 
        "ssoToken": "HORSE_TOKEN", 
        "state": "SK", 
        "status": "paid", 
        "taxonomyId": [
            "beautysvc"
        ], 
        "updatedDateTime": "2015-01-01 01:00:00Z", 
        "workNumber": "306-555-0409", 
        "zip": "S7K 5B8"
    }, 
    "AC-B0S4N4L3": {
        "accountGroupId": "AG-123457", 
        "accountId": "AC-B0S4N4L3", 
        "accountOrigin": "ui", 
        "address": "567 1113th Street", 
        "billingCode": "", 
        "city": "Saskatoon", 
        "companyName": "Bushnells Cow Farm", 
        "country": "CAN", 
        "createdDateTime": "2015-01-01 01:00:00Z", 
        "customerIdentifier": "COWFARM", 
        "marketId": "market2", 
        "pid": "DYB", 
        "ssoToken": "COW_TOKEN", 
        "state": "SK", 
        "status": "paid", 
        "taxonomyId": [
            "beautysvc"
        ], 
        "updatedDateTime": "2015-01-01 01:00:00Z", 
        "workNumber": "306-555-0400", 
        "zip": "S7K 5B8"
    }
}

Search Accounts v1.0

Search accounts.

Rate limit: 300/minute
Supports paged results nextUrl
Supports totalResults

POST/GET https://social-marketing-api.vendasta.com/api/v1/account/search/

Parameter	Required?	Type	Multiples?	Notes
`query`		`string`		Query used to search accounts.
`pageSize`		`int`		Must be a positive integer.

Response codes

Used by VAPI documentation generator

200: Account search results returned.

Example response

"data": [
    {
        "accountGroupId": "AG-123456", 
        "accountId": "AC-B0S4N3L3", 
        "accountOrigin": "ui", 
        "address": "567 113th Street", 
        "billingCode": "", 
        "city": "Saskatoon", 
        "companyName": "Bushnells Horse Farm", 
        "country": "CAN", 
        "createdDateTime": "2015-01-01 01:00:00Z", 
        "customerIdentifier": "HORSEFARM", 
        "marketId": "market1", 
        "pid": "DYB", 
        "ssoToken": "HORSE_TOKEN", 
        "state": "SK", 
        "status": "paid", 
        "taxonomyId": [
            "beautysvc"
        ], 
        "updatedDateTime": "2015-01-01 01:00:00Z", 
        "workNumber": "306-555-0409", 
        "zip": "S7K 5B8"
    }, 
    {
        "accountGroupId": "AG-123457", 
        "accountId": "AC-B0S4N4L3", 
        "accountOrigin": "ui", 
        "address": "567 1113th Street", 
        "billingCode": "", 
        "city": "Saskatoon", 
        "companyName": "Bushnells Cow Farm", 
        "country": "CAN", 
        "createdDateTime": "2015-01-01 01:00:00Z", 
        "customerIdentifier": "COWFARM", 
        "marketId": "market2", 
        "pid": "DYB", 
        "ssoToken": "COW_TOKEN", 
        "state": "SK", 
        "status": "paid", 
        "taxonomyId": [
            "beautysvc"
        ], 
        "updatedDateTime": "2015-01-01 01:00:00Z", 
        "workNumber": "306-555-0400", 
        "zip": "S7K 5B8"
    }
]

Account - V2

These endpoints are used by our partners who manage accounts within Social Marketing.

Create Account v2.0

Create account.

Rate limit: 300/minute

POST https://social-marketing-api.vendasta.com/api/v2/account/create/

Parameter Required? Type Multiples? Notes

address string The company address.

city string The company city.

companyName string The user's company name.

country string The company's 2-letter country code (for example US, CA, or UK).

zip string The company's zip or postal code.

accountGroupId string If provided, the accountGroupId will be used to link the new account to the supplied accountGroupId's associated Social Profile.
If an accountGroupId is specified, the following fields will be ignored (though they are still required, dummy values may be provided): address, city, state, country, zip, companyName, latitude, longitude, marketId, taxId, workNumber, tag. These values will be pulled from the current data for the account group specified by the given accountGroupId

businessCategory

string

A general business category that will be used to provide relevant content. If category is not provided it will default to "OTH". Allowed options are specified by a key that maps to a category value. Either businessCategory or one or more instances of taxonomyId must be specified. Specifying both is not allowed. The category keys and related values are listed below:

Key	Category
AGRI	Agriculture and Mining
ARTS	Arts and Entertainment
AUTO	Automotive
CARE	Personal Care and Services
CON	Construction
EDU	Education
FIN	Financial Services
FOOD	Food and Dining
GOV	Government
HOME	Home and Garden
INDS	Industrial Goods and Manufacturing
LEGAL	Legal Services
MED	Health and Medical
OTH	Other
PRO	Business and Professional Services
REAL	Real Estate
REC	Sports and Recreation
RET	Retail
TRANS	Transportation
TRAVEL	Travel and Tourism

businessCategory (if provided) must belong to a preset list

DEPRECATED: This field is not being used anymore.

callTrackingNumber string The list of call tracking numbers. As entered by the user.

customerIdentifier string An optional string with which to differentiate between accounts. Must be unique across all accounts for the partner.

latitude float E.g., "45.234887". If provided, Longitude must be provided as well. Must be on the range [-90.0, 90.0]. If specified, longitude must also be specified.

longitude float E.g., "-58.245234". If provided, Latitude must be provided as well. Must be on the range [-180.0, 180.0]. If specified, latitude must also be specified.

marketId string Determines which market is set for the account. Accepts Market Key value from list of markets market id must belong to the list of available markets in partner central

service

string

A specific service or industry that the company is in (e.g., "dentist","restaurant","pizza").

DEPRECATED: This field is not being used anymore.

ssoToken string If provided, this will be the SSO token used for single sign-on mechanics (if applicable). May be the same as accountId. If not provided, accountId will be used as the SSO token.

state string The company's state or province code (for example MA, NY, or NJ).

tag string Tag to apply to the account

taxonomyId string Taxonomy ID that will be used to provide relevant content. Either businessCategory or one or more instances of taxonomyId must be specified. Specifying both is not allowed. taxonomyId (if provided) Maximum instances: 3

workNumber string The 10 digit work phone number (no spaces or dashes).

Response codes

200: Account created.
400: Bad request, likely due to invalid parameters. See the message for details.
401: Invalid apiUser/apiKey combination
404: The Account Group (parameter "accountGroupId") could not be found.
409: A unique identifier is already in use. See the message for details.

Example response

Successful account creation response.

"data": {
    "accountGroupId": "AG-KLNC662J", 
    "accountId": "AC-JWGGGWH7", 
    "address": "555 white rd", 
    "billingCode": null, 
    "callTrackingNumber": [
        "7777777777", 
        "8888888888"
    ], 
    "city": "Toronto", 
    "companyName": "company", 
    "country": "Canada", 
    "createdDateTime": "2014-01-15T22:35:43Z", 
    "customerIdentifier": null, 
    "latitude": "52.125948", 
    "longitude": "-106.663286", 
    "marketId": "Eastern Canada", 
    "pid": "ABC", 
    "ssoToken": "AC-JWGGGWH7", 
    "state": "Ontario", 
    "status": "paid", 
    "taxonomyId": [
        "Other"
    ], 
    "updatedDateTime": "2014-01-15T22:35:43Z", 
    "workNumber": [
        "5555555555", 
        "5555555666"
    ], 
    "zip": "H0H 0H0"
}

Update Account v2.0

Update an account.

To update an account, provide either the accountId or the customerIdentifier.

Rate limit: 300/minute

POST https://social-marketing-api.vendasta.com/api/v2/account/update/

Parameter Required? Type Multiples? Notes

accountId string The account's ID string.

address string The company address.

businessCategory

string

Key	Category
AGRI	Agriculture and Mining
ARTS	Arts and Entertainment
AUTO	Automotive
CARE	Personal Care and Services
CON	Construction
EDU	Education
FIN	Financial Services
FOOD	Food and Dining
GOV	Government
HOME	Home and Garden
INDS	Industrial Goods and Manufacturing
LEGAL	Legal Services
MED	Health and Medical
OTH	Other
PRO	Business and Professional Services
REAL	Real Estate
REC	Sports and Recreation
RET	Retail
TRANS	Transportation
TRAVEL	Travel and Tourism