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.


Sites

V3 External APIs used for managing Sites.


Create a Site v3.0

A single microsite is specified using a JSON dictionary encoding. The dictionary for a single microsite contains all the details necessary to create the microsite, including titles, headings, images, videos, pages, etc.

  • Rate limit: 300/minute
POST https://presence-builder-api.vendasta.com/api/v3/site/create/
Parameter Required? Type Multiples? Notes
identifier string A short ID for the microsite. Must be unique across the entire partner. One-to-one with a particular microsite. must be unique
accountGroupId string An account group ID. An account group will be created if an account group ID is not specified. 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, website. These values will be pulled from the current data for the account group specified by the given accountGroupId. must be a valid account group
address string A street address
announcement string An announcement that is intended to be updated frequently and appears prominently in a call-to-action location.
DEPRECATED: This field is deprecated.
callTrackingNumber string The list of call tracking numbers. Should be formatted for display. If a valid country code is given, phone number is formatted according to local phone number format. E.g., if 'CA' is provided as country, phone number is formatted as (306) 555-5555
city string The name of a city
color string The primary color for the microsite. For hex values, you must include the "#" leading character. E.g., "#99CC00". must be a valid hex color
companyName string The name of the microsite appears in the header of each page.
country string A country name or 2 character code. If valid country name is provided, it is converted to corresponding country code.
customDomain string A custom domain e.g. "customDomain" : "m.abc.com". Appropriate setup on the customer side needs to be performed to make this active. must be a valid url
customerIdentifier string A partner's microsite identifier. must be unique
email string An e-mail address must be a valid email address
facebookUrl string A link to a Facebook Page associated with this microsite.
filename string Default: "unknown"
foursquareUrl string A link to a Foursquare Venue associated with this microsite.
googleplusUrl string A link to a YouTube channel associated with this microsite.
host string Host for the slug to be appended to. Must be one of the valid partner's hosts that uses slugs. If not provided, the first host (default) will be used. must already exist
hours string The hours attribute is used to specify the Hours of Operation section, if applicable. The attribute is a nested JSON dictionary, yielding something like the following:
 "hours": { "monday": {"open": "9:00 AM", "close": "5:00 AM"}, ...} 
Each day of the week can have an open and a close string, plus an open2 and a close2 string for split hours (e.g., "9:00AM - 12:00PM, 1:00PM - 5:00PM"). Additionally, each day of the week can support an arbitrary note. There are also some attributes specified globally: open24, holidays, and other. open24 is a boolean flag, and needs to be encoded like the following:
 "open24": true (or) "open24": false 
Hours dictionary attributes:
monday, tuesday, wednesday, thursday, friday, saturday, sunday day of week dictionary (see below)
open24 boolean, either true or false
holidaysstring
otherstring
Day of week dictionary attributes:
openShould be a locale-appropriate time. E.g., "9:00 AM", "1:30pm", "17:15", etc.
closeAs above
open2As above
close2As above
noteAn arbitrary note that can be used in addition to, or in place of, the above attributes.
In an hours dictionary specification, all fields are optional, which provides for a very flexible interface. Below is an example, though your approach may be very different.
 "hours": { "monday": { "open": "9:00 am", "close": "5:00 pm", "note": "closed for lunch" }, "tuesday": { "open": "9:00 am", "close": "5:00 pm" }, "friday": { "open": "9:00 am", "close": "5:00 pm" }, "wednesday": { "open": "9:00 am", "close": "5:00 pm" }, "thursday": { "open": "9:00 am", "close": "5:00 pm", "open2": "6:00pm", "close2": "9:00pm" }, "holiday": "Closed for stat holidays", "open24": false } 
Note the above example of split hours on Thursday.
instagramUrl string A link to a Instagram Profile associated with this microsite.
latitude float E.g., "45.234887". Must be on the range [-90.0, 90.0]. If specified, longitude must also be specified.
layout string The layout to use for the website. Choices are: 'short', 'tall', 'responsive', and 'location'. Default: "location"
linkedinUrl string A link to a LinkedIn Profile associated with this microsite.
logoUrl string E.g., "http://www.example.com/foo.png". The logo will be read and imported into our system. Each batch import will provoke a check to see if the image has been updated and requires re-import. must be a valid image
longitude float E.g., "-58.245234". 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. Takes Market Key value from list of markets. must be a valid market id
notificationUrl string
page string The pages attribute is used to identify the set of pages for the microsite, as a list of page dictionaries. You must have at least 1 page, but you may not exceed 15 pages per microsite. When updating a microsite page, the slug attribute is used to identify the existing page. If a slug is used that is not present, a new page with that slug will be created. If a slug that previously existed is not in the pages list, the old page will be deleted and will return a 404 on subsequent requests. If the slug matches an existing page, that page will be updated with the new values.
Page dictionary attributes (* means required):
slug* The page slug is the string that identifies the page within a microsite. If a slug changes, the old page will be deleted (and requests for it will return a 404), and a new page will be created. Can only be letters, numbers, and dashes.
template* One of: "Custom", "Images", "Contact", "Videos", "Coupons". Identifies the type of page content. Additional page dictionary attributes may be specified depending on the selected template - see below. This field is case-sensitive.
tab_name* The name that appears on the navigation item.
h1* The content that appears in the h1 tag for the page. Do not include the

tags themselves.
title* The content that appears in the meta title tag for the page. Do not include the tags themselves.
meta_keywords The content for the meta keywords tag for the page. Do not include the tag itself.
meta_description The content for the meta description tag for the page. Do not include the tag itself.
top_content Free content that appears before any content determined by the page template.
bottom_content Free content that appears after any content determined by the page template.
email Only for Contact template. This is the email address that will receive contact requests from this page.
images List of image urls. Only for Images template. The images that should be displayed on this page. We will import these images into our system and resize them as appropriate. On subsequent imports, we will check to see if the image has been updated and re-import if necessary.
mobile_gallery_style Only for Images template. How the images will be displayed on a mobile device. E.g., "table", "photoswipe". Default is "table".
desktop_gallery_style Only for Images template. How the images will be displayed on a desktop computer. E.g., "table", "lightbox". Default is "table".
videos List of video urls or video dictionaries. Only for Videos template. The videos that should be displayed on this page.
coupons List of coupon dictionaries. Only for Coupons template. The coupons that should be displayed on this page.

Default Page
If a page is not supplied, the default page is as follows:
 "page": [{ 'slug': 'home', 'template': 'Custom', 'tab_name': 'Home', 'title': 'Home', 'h1': 'Home', }] 

Images
The images attribute is used to specify a list of images for an Images page. The list can either be a list of string urls, or a list of dictionaries depending on how much you wish to specify. You can specify up to 20 images per Images page. JPG, GIF, PNG, and WEBP images are supported. An example images specification is as follows:
 "images": [ "http://www.example.com/img1.png", "http://www.example.com/img2.jpg", "http://www.example.com/img3.gif" ] 
These images will be imported into our system and served from our servers. On subsequent batch imports, we will check to see if the images have been updated and re-import them if necessary. It is an important optimization for the server serving the original images to emit Etag or Last-Modified headers. These headers will be used to determine if an image has been updated or not.
Image dictionary attributes (* means required):
url* The url for the image content. The image will be imported into our system.
caption The caption for the image.
alt_text The alt text for the image.
title The title text for the image.

Videos
The videos attribute specifies a list of videos to appear on the Videos page. The list can either be a list of string urls, or a list of dictionaries depending on how much you wish to specify. Note that video and thumbnail content are served from the urls provided; these items are not imported into our system.
Video dictionary attributes (* means required):
url* The url for the video content. The video will be served from this location and not imported into our system. For YouTube urls, we will automatically retrieve thumbnails, titles, etc. if they are not specified.
phone_url A secondary URL for a video that is served on the mobile site, the "url" is embedded while the "phone_url" is directly linked.
thumbnail_url The url for a thumbnail for the video. The thumbnail will be served from this location and not imported into our system.
title The title for the video.
caption A caption or description for the video.
duration The duration of the video.
Minimally, the videos page attribute can be a simple list of urls to videos, like the following:
 "videos": [ "http://www.youtube.com/watch?v=zzfQwXEqYaI", "http://www.youtube.com/watch?v=ntT7v47RIds" ]
Alternatively, if you want to specify thumbnails, captions, duration, etc., you can provide a list of video dictionaries:
 "videos": [ { "url": "http://www.example.com/vid1.mp4", "thumbnail_url": "http://www.example.com/th1.jpg", "title": "Watch us in action!" }, { "url": "http://www.example.com/vid2.mp4", "title": "Last Thursday's Outing" }] 

Coupons
The coupons attribute specifies a list of coupons to appear on the Coupons page. The list is a list of coupon dictionaries. Note that the coupon image is served from the url provided; this item is not imported into our system.
Coupon dictionary attributes (* means required):
title* The title of the coupon. This is the minimal amount of data required to display a coupon.
detail The detail text for the coupon giving additional information.
image_url A small image that is displayed at the top of the coupon, it is served from this url and not imported. Maximum size 150x100 pixels.
category The Category of the coupon, any text string is possible, can be empty.
start The start date at which the coupon becomes active formatted as YYYY-MM-DD eg. 2011-05-25.
end The end date after which the coupon is no longer available formatted the same way the start date is.
expiry The expiry date of the coupon, the day when the customer can no longer use the coupon.
This is an example how the list of coupon dictionaries can look:
 "coupons": [ { "end": "2011-11-30", "title": "Save 20 %", "detail": "On any purchase", "category" : "Auto", "expiry": "2011-11-30", "start": "2011-08-15", "image_url": "http://example.com/image.png" }, { "title": "Buy one get one free every day after 5pm" }] 
Default: ["{\"slug\": \"home\", \"template\": \"Custom\", \"tab_name\": \"Home\", \"title\": \"Home\", \"h1\": \"Home\"}", "{\"slug\": \"review\", \"template\": \"Reviews\", \"tab_name\": \"Reviews\", \"title\": \"Reviews\"}"] Maximum instances: 15
pinterestUrl string A link to a Pinterest Profile associated with this microsite.
place string A colloquial name that may be used in keywords, etc. E.g., "Big Apple" or "Twin Cities".
rssUrl string A link to a blob or an RSS feed associated with this microsite.
service string A comma separated list of likely search terms for the business. Used in meta-content for SEO. e.g. "plumbing, sewer service, commercial plumbing". This will validate the service arg accepts up to 3 items
slug string For a slug "this-is-the-slug", the url for the microsite becomes: "http://m.partner.com/this-is-the-slug/". One-to-one with a particular microsite. Can only be letters, numbers, and dashes. When the provided slug already exists for the host, a unique slug is generated. The desired slug is used in combination with either the sites city, zip or if all else fails a random identifier. E.g., if the slug "this-is-the-slug" exists, then a unique slug "this-is-the-slug-portland" is generated, and the url for the microsite becomes: "http://m.partner.com/this-is-the-slug-portland/
ssoToken string An SSO token to grant authorization for this site. Maximum length of 200.
state string A state name or 2 character code. It is also validated if valid country is provided.
tagline string A short tagline that appears in the header beneath the name.
taxId string must be a valid tax id Maximum instances: 3
twitterUrl string A link to a twitter profile associated with this microsite.
validateOnlyFlag boolean If provided, the site will not actually be committed, but the arguments will be validated to ensure the site creation would succeed. Default: false
website string The company website, if one exists other than the microsite. Must start with http:// or https:// must be a valid url
workNumber string The list of work phone number for the site. Should be formatted for display. If a valid country code is given, phone number is formatted according to local phone number format. E.g., if 'CA' is provided as country, phone number is formatted as (306) 555-5555
youtubeUrl string A link to a YouTube channel associated with this microsite.
zip string A zip or postal code
Response codes

Returns dictionary of status code integer to a string message

200
Created the Microsite successfully
400
Invalid Microsite specification
409
A host->slug mapping already exists, so the one provided cannot be used
Example response

An example response from a successful site creation call. If any deprecated fields were used in the create call, the will be listed under deprecationWarning.

Note the slug that you request may not be the final slug, so ensure that you check this response to know what the final slug that was used.

"data": {
    "data": {
        "accountGroupId": "partner-central-ui", 
        "identifier": "M-42879345", 
        "message": "Site has been created/updated successfully.", 
        "msid": "MS-FAKEMSID", 
        "slug": "joes-plumbing-and-heating", 
        "warnings": [
            "Error processing page \"contact\" for site \"MS-ABCD123\" and partner \"ABC\".  Page will be skipped.", 
            "The following image urls could not be uploaded: \"http://www.example.com/my-image.jpg\""
        ]
    }, 
    "deprecationWarning": {
        "announcement": "This field is deprecated."
    }, 
    "requestId": "53bc6f0e00ff05131cc9a1e9530001737e6d6963726f736974652d7465737400016461696c79000100", 
    "responseTime": 741, 
    "status": 200, 
    "version": "3.1"
}

Update a Site v3.0

A single microsite is specified using an msid and a JSON dictionary encoding. The dictionary for a single microsite contains all the details necessary to update the microsite; including titles, headings, images, videos, pages, etc.

  • Rate limit: 300/minute
POST https://presence-builder-api.vendasta.com/api/v3/site/update/
Parameter Required? Type Multiples? Notes
identifier string A short ID for the microsite. Must be unique across the entire partner. One-to-one with a particular microsite. Validate that we can get an msid using the pmsid and pid/apiuser passed in.
page string The pages attribute is used to identify the set of pages for the microsite, as a list of page dictionaries. You must have at least 1 page, but you may not exceed 15 pages per microsite. When updating a microsite page, the slug attribute is used to identify the existing page. If a slug is used that is not present, a new page with that slug will be created. If a slug that previously existed is not in the pages list, the old page will be deleted and will return a 404 on subsequent requests. If the slug matches an existing page, that page will be updated with the new values.
Page dictionary attributes (* means required):
slug* The page slug is the string that identifies the page within a microsite. If a slug changes, the old page will be deleted (and requests for it will return a 404), and a new page will be created. Can only be letters, numbers, and dashes.
template* One of: "Custom", "Images", "Contact", "Videos", "Coupons". Identifies the type of page content. Additional page dictionary attributes may be specified depending on the selected template - see below. This field is case-sensitive.
tab_name* The name that appears on the navigation item.
h1* The content that appears in the h1 tag for the page. Do not include the

tags themselves.
title* The content that appears in the meta title tag for the page. Do not include the tags themselves.
meta_keywords The content for the meta keywords tag for the page. Do not include the tag itself.
meta_description The content for the meta description tag for the page. Do not include the tag itself.
top_content Free content that appears before any content determined by the page template.
bottom_content Free content that appears after any content determined by the page template.
email Only for Contact template. This is the email address that will receive contact requests from this page.
images List of image urls. Only for Images template. The images that should be displayed on this page. We will import these images into our system and resize them as appropriate. On subsequent imports, we will check to see if the image has been updated and re-import if necessary.
mobile_gallery_style Only for Images template. How the images will be displayed on a mobile device. E.g., "table", "photoswipe". Default is "table".
desktop_gallery_style Only for Images template. How the images will be displayed on a desktop computer. E.g., "table", "lightbox". Default is "table".
videos List of video urls or video dictionaries. Only for Videos template. The videos that should be displayed on this page.
coupons List of coupon dictionaries. Only for Coupons template. The coupons that should be displayed on this page.

Default Page
If a page is not supplied, the default page is as follows:
 "page": [{ 'slug': 'home', 'template': 'Custom', 'tab_name': 'Home', 'title': 'Home', 'h1': 'Home', }] 

Images
The images attribute is used to specify a list of images for an Images page. The list can either be a list of string urls, or a list of dictionaries depending on how much you wish to specify. You can specify up to 20 images per Images page. JPG, GIF, PNG, and WEBP images are supported. An example images specification is as follows:
 "images": [ "http://www.example.com/img1.png", "http://www.example.com/img2.jpg", "http://www.example.com/img3.gif" ] 
These images will be imported into our system and served from our servers. On subsequent batch imports, we will check to see if the images have been updated and re-import them if necessary. It is an important optimization for the server serving the original images to emit Etag or Last-Modified headers. These headers will be used to determine if an image has been updated or not.
Image dictionary attributes (* means required):
url* The url for the image content. The image will be imported into our system.
caption The caption for the image.
alt_text The alt text for the image.
title The title text for the image.

Videos
The videos attribute specifies a list of videos to appear on the Videos page. The list can either be a list of string urls, or a list of dictionaries depending on how much you wish to specify. Note that video and thumbnail content are served from the urls provided; these items are not imported into our system.
Video dictionary attributes (* means required):
url* The url for the video content. The video will be served from this location and not imported into our system. For YouTube urls, we will automatically retrieve thumbnails, titles, etc. if they are not specified.
phone_url A secondary URL for a video that is served on the mobile site, the "url" is embedded while the "phone_url" is directly linked.
thumbnail_url The url for a thumbnail for the video. The thumbnail will be served from this location and not imported into our system.
title The title for the video.
caption A caption or description for the video.
duration The duration of the video.
Minimally, the videos page attribute can be a simple list of urls to videos, like the following:
 "videos": [ "http://www.youtube.com/watch?v=zzfQwXEqYaI", "http://www.youtube.com/watch?v=ntT7v47RIds" ]
Alternatively, if you want to specify thumbnails, captions, duration, etc., you can provide a list of video dictionaries:
 "videos": [ { "url": "http://www.example.com/vid1.mp4", "thumbnail_url": "http://www.example.com/th1.jpg", "title": "Watch us in action!" }, { "url": "http://www.example.com/vid2.mp4", "title": "Last Thursday's Outing" }] 

Coupons
The coupons attribute specifies a list of coupons to appear on the Coupons page. The list is a list of coupon dictionaries. Note that the coupon image is served from the url provided; this item is not imported into our system.
Coupon dictionary attributes (* means required):
title* The title of the coupon. This is the minimal amount of data required to display a coupon.
detail The detail text for the coupon giving additional information.
image_url A small image that is displayed at the top of the coupon, it is served from this url and not imported. Maximum size 150x100 pixels.
category The Category of the coupon, any text string is possible, can be empty.
start The start date at which the coupon becomes active formatted as YYYY-MM-DD eg. 2011-05-25.
end The end date after which the coupon is no longer available formatted the same way the start date is.
expiry The expiry date of the coupon, the day when the customer can no longer use the coupon.
This is an example how the list of coupon dictionaries can look:
 "coupons": [ { "end": "2011-11-30", "title": "Save 20 %", "detail": "On any purchase", "category" : "Auto", "expiry": "2011-11-30", "start": "2011-08-15", "image_url": "http://example.com/image.png" }, { "title": "Buy one get one free every day after 5pm" }] 
slug string For a slug "this-is-the-slug", the url for the microsite becomes: "http://m.partner.com/this-is-the-slug/". One-to-one with a particular microsite. Can only be letters, numbers, and dashes. When the provided slug already exists for the host, a unique slug is generated. The desired slug is used in combination with either the sites city, zip or if all else fails a random identifier. E.g., if the slug "this-is-the-slug" exists, then a unique slug "this-is-the-slug-portland" is generated, and the url for the microsite becomes: "http://m.partner.com/this-is-the-slug-portland/
address string A street address
callTrackingNumber string The list of call tracking numbers. Should be formatted for display. If a valid country code is given, phone number is formatted according to local phone number format. E.g., if 'CA' is provided as country, phone number is formatted as (306) 555-5555
city string The name of a city
color string The primary color for the microsite. For hex values, you must include the "#" leading character. E.g., "#99CC00".
companyName string The name of the microsite appears in the header of each page.
country string A country name or 2 character code. If valid country name is provided, it is converted to corresponding country code.
customDomain string A custom domain e.g. "customDomain" : "m.abc.com". Appropriate setup on the customer side needs to be performed to make this active.
customerIdentifier string A partner's microsite identifier.
email string An e-mail address
facebookUrl string A link to a Facebook Page associated with this microsite.
filename string
foursquareUrl string A link to a Foursquare Venue associated with this microsite.
googleplusUrl string A link to a YouTube channel associated with this microsite.
host string Host for the slug to be appended to. Must be one of the valid partner's hosts that uses slugs. If not provided, the first host (default) will be used. Validates the host is one of the partner's configured hosts
hours string The hours attribute is used to specify the Hours of Operation section, if applicable. The attribute is a nested JSON dictionary, yielding something like the following:
 "hours": { "monday": {"open": "9:00 AM", "close": "5:00 AM"}, ...} 
Each day of the week can have an open and a close string, plus an open2 and a close2 string for split hours (e.g., "9:00AM - 12:00PM, 1:00PM - 5:00PM"). Additionally, each day of the week can support an arbitrary note. There are also some attributes specified globally: open24, holidays, and other. open24 is a boolean flag, and needs to be encoded like the following:
 "open24": true (or) "open24": false 
Hours dictionary attributes:
monday, tuesday, wednesday, thursday, friday, saturday, sunday day of week dictionary (see below)
open24 boolean, either true or false
holidaysstring
otherstring
Day of week dictionary attributes:
openShould be a locale-appropriate time. E.g., "9:00 AM", "1:30pm", "17:15", etc.
closeAs above
open2As above
close2As above
noteAn arbitrary note that can be used in addition to, or in place of, the above attributes.
In an hours dictionary specification, all fields are optional, which provides for a very flexible interface. Below is an example, though your approach may be very different.
 "hours": { "monday": { "open": "9:00 am", "close": "5:00 pm", "note": "closed for lunch" }, "tuesday": { "open": "9:00 am", "close": "5:00 pm" }, "friday": { "open": "9:00 am", "close": "5:00 pm" }, "wednesday": { "open": "9:00 am", "close": "5:00 pm" }, "thursday": { "open": "9:00 am", "close": "5:00 pm", "open2": "6:00pm", "close2": "9:00pm" }, "holiday": "Closed for stat holidays", "open24": false } 
Note the above example of split hours on Thursday.
instagramUrl string A link to a Instagram Profile associated with this microsite.
latitude float E.g., "45.234887".
layout string The layout to use for the website. Choices are: 'short', 'tall', 'responsive', and 'location'.
linkedinUrl string A link to a LinkedIn Profile associated with this microsite.
logoUrl string E.g., "http://www.example.com/foo.png". The logo will be read and imported into our system. Each batch import will provoke a check to see if the image has been updated and requires re-import.
longitude float E.g., "-58.245234".
marketId string Determines which market is set for the account. Takes Market Key value from list of markets. Checks to make sure that the marketId being passed in exists for the partner
notificationUrl string Validates the notification URL
pinterestUrl string A link to a Pinterest Profile associated with this microsite.
place string A colloquial name that may be used in keywords, etc. E.g., "Big Apple" or "Twin Cities".
rssUrl string A link to a blob or an RSS feed associated with this microsite.
service string A comma separated list of likely search terms for the business. Used in meta-content for SEO. e.g. "plumbing, sewer service, commercial plumbing". This will validate the service arg accepts up to 3 items
ssoToken string An SSO token to grant authorization for this site. Maximum length of 200.
state string A state name or 2 character code. It is also validated if valid country is provided.
tagline string A short tagline that appears in the header beneath the name.
taxId string Ensure the number of tax id values provided are not greater than the maximum allowed. Maximum instances: 3
twitterUrl string A link to a twitter profile associated with this microsite.
website string The company website, if one exists other than the microsite. Must start with http:// or https://
workNumber string The list of work phone number for the site. Should be formatted for display. If a valid country code is given, phone number is formatted according to local phone number format. E.g., if 'CA' is provided as country, phone number is formatted as (306) 555-5555
youtubeUrl string A link to a YouTube channel associated with this microsite.
zip string A zip or postal code
Response codes

Returns dictionary of status code integer to a string message

200
Updated the Microsite successfully
400
Invalid Microsite specification
409
A host->slug mapping already exists, so the one provided cannot be used
Example response

An example of updating a Microsite. Call the Update API in the same way you would call the Create API, and change the fields you want to update on the site.

"data": {
    "data": {
        "accountGroupId": "partner-central-ui", 
        "identifier": "M-42879345", 
        "message": "Site has been created/updated successfully.", 
        "msid": "MS-FAKEMSID", 
        "warnings": [
            "Error processing page \"contact\" for site \"MS-ABCD123\" and partner \"ABC\".  Page will be skipped.", 
            "The following image urls could not be uploaded: \"http://www.example.com/my-image.jpg\""
        ]
    }, 
    "deprecationWarning": {
        "announcement": "This field is deprecated."
    }, 
    "requestId": "53bc6f0e00ff05131cc9a1e9530001737e6d6963726f736974652d7465737400016461696c79000100", 
    "responseTime": 741, 
    "status": 200, 
    "version": "3.1"
}

Delete a Site v3.0

Delete a microsite.

  • Rate limit: 300/minute
POST https://presence-builder-api.vendasta.com/api/v3/site/delete/
Parameter Required? Type Multiples? Notes
msid string A short system defined ID assigned to a microsite during creation process An internal identifier that is unique across the entire product.
Response codes

Returns dictionary of status code integer to a string message

200
Deleted the Microsite successfully
404
Partner or Microsite was not found
Example response

An example response from a successful Delete API call

"data": Success. The site is being deleted.

Search Sites v3.0

Search for microsites using a custom query. Not including the query parameter will result in all the microsites under the specified partner being returned. The search actually returns search documents, which do not necessarily encapsulate all data about a microsite. However, the data encapsulated should be more than enough for most purposes.

  • Rate limit: 300/minute
  • Supports paged results nextUrl
  • Supports totalResults
POST/GET https://presence-builder-api.vendasta.com/api/v3/site/search/
Parameter Required? Type Multiples? Notes
query string Query used to search sites.
pageSize int Must be a positive integer.
Response codes

Returns dictionary of status code integer to a string message

200
Successfully returned a list of Microsite search documents
Example response

A list of microsite documents whose fields match the provided query.

"data": {
    "data": {
        "addReviewUrl": "http://pdqs.mobi/your-fantastic-slug/review/add/", 
        "address1": "556 Joe's Road", 
        "address2": "556 Joe's Street", 
        "blurb": "Best plumbers ever", 
        "city": "Detroit", 
        "color": "#99CC00", 
        "companyName": "Joe's Plumbing and Heating", 
        "country": "US", 
        "created": "2013-11-06 21:34:50.299297", 
        "customerIdentifier": "jpah-8927", 
        "email": "joe@joesplumbingandheating.com", 
        "mappings": [
            "west-coast.partner.com/joes-plumbing-and-heating-route-1", 
            "west-coast.partner.com/joes-plumbing-and-heating-route-2"
        ], 
        "marketId": "western-us", 
        "msid": "MS-FAKEMSID", 
        "phone": "555-5555", 
        "pid": "ABC", 
        "place": "Big Apple", 
        "service": [
            "plumbing", 
            "sewer service", 
            "commercial plumbing"
        ], 
        "ssoToken": "joes-plumbing-and-heating-sso-token", 
        "state": "NY", 
        "updated": "2014-5-06 21:34:50.299297", 
        "useWebsiteForFullSiteLink": true, 
        "website": "http://www.joesplumbingandheating.com", 
        "zip": "H0H 0H0"
    }, 
    "numberFoundAccuracy": 100, 
    "requestId": "fd4eb2fdbf7ff4c16ed7eda285b9dcb8c47c0d072c9b80108afeff55ea879c2cbc", 
    "responseTime": 741, 
    "status": 200, 
    "totalResults": 1, 
    "version": "3.0"
}

Google My Business Insights

Endpoints for dealing with Google My Business Insights.


Get Google My Business Insights Api v3.0

Get a list of Google My Business Insights entities for an account.

  • Rate limit: 300/minute
POST/GET https://presence-builder-api.vendasta.com/api/v3/googleMyBusinessInsights/get/
Parameter Required? Type Multiples? Notes
accountGroupId string An account group ID. Checks that the account group belongs to the partner.
endDate date The date for the end of the range of insights requested. Must be after the start date.
startDate date The date for the start of the range of insights requested.
Example response

An example of a successful get of Google My Business Insights data.

"data": [
    {
        "account_id": "123456789123456789123", 
        "actions_driving_directions": 0, 
        "actions_phone": 1, 
        "actions_website": 2, 
        "end_date": "2018-02-21T07:00:00Z", 
        "location_id": "987654321987654321987", 
        "queries_direct": 15, 
        "queries_indirect": 57, 
        "start_date": "2018-02-20T07:00:00Z", 
        "views_maps": 15, 
        "views_search": 60
    }, 
    {
        "account_id": "123456789123456789123", 
        "actions_driving_directions": 0, 
        "actions_phone": 0, 
        "actions_website": 3, 
        "end_date": "2018-02-22T07:00:00Z", 
        "location_id": "987654321987654321987", 
        "queries_direct": 6, 
        "queries_indirect": 55, 
        "start_date": "2018-02-21T07:00:00Z", 
        "views_maps": 17, 
        "views_search": 54
    }
]

Social

These end-points are used for managing Social integration with Sites.


Remove a Site from a Facebook page. v2.0

Removes the specified Site from the specified Facebook page. The More Info tab will be removed from the Facebook page.

POST https://presence-builder-api.vendasta.com/api/v2/facebookTab/remove/
Parameter Required? Type Multiples? Notes
facebookPageId string A short ID for the Facebook page. Assigned by Facebook to each unique page.
identifier string A short ID for the microsite, must be unique across the entire import and must match previous imports for updates to work correctly. One-to-one with a particular microsite.
msid string A short ID for the microsite. Assigned by VendAsta to each unique microsite.
Response codes

Returns dictionary of status code integer to a string message

200
Successfully removed the Microsite from the Facebook page
400
There was a problem in your request
404
Microsite was not found
Example response

An example response for removing the link between a Microsite and a Facebook Page

"data": {
    "facebookPageId": "12345678901", 
    "identifier": "the-burger-dive", 
    "msid": "MS-SOMEMSID"
}

Add a Site to Facebook Page v2.0

Adding an existing site to Facebook Page as More Info tab

POST https://presence-builder-api.vendasta.com/api/v2/facebookTab/add/
Parameter Required? Type Multiples? Notes
facebookPageId string A Facebook page identifier. To use the current API, either facebookPageId or facebookUrl must be specified but not both.
facebookUrl string A Facebook page url To use the current API, either facebookPageId or facebookUrl must be specified but not both.
facebookUserId string A Facebook user identifier. Optional. Only needed when current partner has no Facebook master user defined and Facebook page ID is present.
identifier string A short customer defined ID for the microsite which identifies the microsite that is requested to be added to given Facebook page. To use the current API, either msid or identifier must be specified but not both.
msid string A short system defined ID assigned to a microsite during creation process. To use current API, either msid or identifier must be specified but not both.
Response codes

Returns dictionary of status code integer to a string message

200
Successfully linked the Microsite to the Facebook page
400
There was a problem in your request
404
Microsite was not found
Example response

An example response for linking a Microsite to a Facebook Page. Note: If you pass in the Facebook URL instead of the Page ID, facebookPageId would be null and facebookUrl would have the URL.

"data": {
    "facebookPageId": "123456789012346", 
    "facebookUrl": "null", 
    "facebookUserId": "123456789012345", 
    "identifier": "null", 
    "msid": "MS-SOMEMSID"
}