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.

Account Groups

app.views.api.v2.account_group

Associate a Business App user with an Account Group v2.0

This end-point is used to create associations between account groups given a Business Center user id.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/accountGroup/associateUser/
Parameter Required? Type Multiples? Notes
agid string A unique account group identifier.
userId string A unique user id.
Response codes

A list of potential status codes that may be returned.

200
If the key was successfully associated
400
If invalid parameters are submitted.
401
If the user id or pid is invalid
404
If the user is not found, or a matching account is not found
500
If an unknown error occurs
Example response

Returns the association key created.

"data": {
    "associationId": "UID-FABDJ4MB-AA4AFDL8-AGID"
}

Account

These external end-points are used for accessing Accounts details.

Create Account v3.0

This end-point is used to create an account.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v3/account/create/
Parameter Required? Type Multiples? Notes
companyName string A descriptive company name.
SEOCategory string Search engine terms related to a business Maximum instances: 3
actionLists string
addPresenceBuilderFlag boolean
addReputationDemoFlag boolean
addReputationFlag boolean
addSocialMarketingFlag boolean
address string The address of the business.
address2 string
brandsCarried string Primary brands carried. e.g. Panasonic, Apple. Total length of brands carried must be less than 256 characters, when joined with commas. Maximum instances: 15
businessLogoUrl string
businessPrimaryPhotoUrl string
callTrackingNumber string A list of call tracking numbers. Maximum instances: 3
cellNumber string The cell number for a business
city string The city of the business.
commonName string A common name for a business (Something it is often referred to as) Maximum instances: 3
competitor string Competitors for a business
contactEmail string The email for someone at the business. If this is provided, it will create a Business App user using contactFirstName, contactLastName and contactPhoneNumber.
contactFirstName string The first name for a contact for a business
contactLastName string The last name for a contact for a business
contactPhoneNumber string The phone number to contact someone at a business
country string The 2-letter country code.
customerIdentifier string A unique identifier.
description string Maximum length: 1000
email string The email for a business
facebookUrl string The fully qualified URL of a Facebook page.
faxNumber string The fax number for a business
foursquareUrl string The fully qualified URL of a FourSquare user.
googleplusUrl string The fully qualified URL of a Google+ page.
healthCareProfessionalInformationJson JSON (see description) Information for a health care professional. Should be supplied as a json dict. (See example response.) Validates all fields passed in.
hoursOfOperationJson JSON (see description) Hours of operation for a business. Should be supplied as a json dict. (See example response.)
instagramUrl string The exact instagram url for a business
keyPerson string A key person for a business Maximum instances: 3
landmark string Reference to the general area of the business. e.g. Downtown Mall. Maximum length: 60
latitude float A float on [-90.0, 90.0]. If specified, longitude must also be specified. Value must be [-90.0, 90.0].
linkedinUrl string The fully qualified URL of a LinkedIn user.
longitude float A float on [-180.0, 180.0]. If specified, latitude must also be specified. Value must be [-180.0, 180.0].
marketId string A valid marketId for this Partner. Must be lowercase letters, numbers or dashes.
paymentMethods string Possible methods: American Express, Android Pay, Apple Pay, Cash, Check, Debit, Diners Club, Discover, MasterCard, PayPal, Samsung Pay, Store Card, Travelers Checks, Visa Payment methods must be one of a set of defined values.
pinterestUrl string The exact pinterest url for a business
place string A textual description of where a business is. ex: 'The Avenue Building'
rmAdminNotes string
rmWelcomeMessage string
rssUrl string The rss feed url for a business
salesPersonId string A unique sales person identifier.
serviceAreaBusinessFlag boolean
servicesOffered string Services offered, e.g. personal tax filing, business tax filing. Total length of services offered must be less than 256 characters, when joined with commas. Maximum instances: 15
shareOfVoiceService string Share of voice services for a business Share of voice services for a business
shortDescription string Maximum length: 200
socialProfileId string A unique social profile identifier.
ssoToken string
state string The state code.
tag string Custom tags. Maximum length: 50 Maximum instances: 15
tagline string The tagline, catchphrase or motto of a business. ex: 'I'm lovin it'.
taxonomyId string Up to 3 can be supplied, must comply with vTaxonomy Ids available from Core. Maximum instances: 3
tollFreeNumber string
twitterSearches string Maximum instances: 3
twitterUrl string The fully qualified URL of a Twitter user.
website string The website of the business.
workNumber string A list of work numbers Maximum instances: 6
youtubeUrl string The exact youtube url for a business
zip string The zip/postal code for the address.
Response codes

A list of potential status codes that may be returned.

201
If the account was successfully created.
400
If invalid parameters are submitted.
404
If no partner with the specified pid exists.
409
If a socialProfileId or marketId is invalid or not registered.
500
An undefined error case
Example response

Returns the new account information.

"data": {
    "accountId": "AG-2AA972E", 
    "actionLists": [
        "campaign X list"
    ], 
    "address": "220 3rd Ave S", 
    "address2": "Suite #405", 
    "brandsCarried": [
        "American Standard", 
        "Flush-O-Matic"
    ], 
    "callTrackingNumber": [
        "3069523875"
    ], 
    "cellNumber": "3062221234", 
    "city": "Saskatoon", 
    "commonName": [
        "Ace Plumbers"
    ], 
    "companyName": "Ace Plumbing", 
    "competitor": [
        "Gary Plumbing"
    ], 
    "contactEmail": "johndoe@example.com", 
    "contactFirstName": "John", 
    "contactLastName": "Doe", 
    "contactPhoneNumber": "1-800-267-2001", 
    "country": "CA", 
    "created": "2013-06-06T19:36:36Z", 
    "customerIdentifier": null, 
    "description": "The number 1 plumber in the greater Saskatoon area! We specialize in everything from out houses to olympic pools.", 
    "email": "office@example.com", 
    "facebookUrl": "https://facebook.com/ace-plumbing", 
    "faxNumber": "3065554444", 
    "foursquareUrl": "https://foursquare.com/ace-plumbing", 
    "googleplusUrl": "https://plus.google.com/ace-plumbing", 
    "healthCareProfessionalInformationJson": {
        "dateOfBirth": "1999-12-31", 
        "email": "smith@jonesmedical.com", 
        "fellowship": [
            "Innitech Medic Co."
        ], 
        "firstName": "Jane", 
        "gender": "Female", 
        "initials": "M", 
        "insurancesAccepted": [
            "All-Tech Insurance", 
            "Happy Acres Industrial Insurance"
        ], 
        "isTakingPatients": true, 
        "lastName": "Smith", 
        "medicalLicenseNumber": "123456789", 
        "nationalProviderIdentifier": "1111111111", 
        "office": "Jones Medical", 
        "professionalCredential": [
            "MD"
        ], 
        "residency": [
            "Houston General Oncology"
        ], 
        "school": [
            "Texas State"
        ], 
        "specialty": [
            "Oncology"
        ], 
        "standardizedTitle": "VP", 
        "stateLicense": "55555"
    }, 
    "hoursOfOperationJson": [
        {
            "closes": "18:00", 
            "dayOfWeek": [
                "Monday", 
                "Tuesday", 
                "Wednesday", 
                "Thursday", 
                "Friday"
            ], 
            "description": "Normal Weekday hours", 
            "opens": "6:00"
        }, 
        {
            "closes": "", 
            "dayOfWeek": [
                "PublicHolidays"
            ], 
            "description": "By appointment only.", 
            "opens": ""
        }
    ], 
    "instagramUrl": "https://instagram.com/ace-plumbing", 
    "keyPerson": [
        "John Doe"
    ], 
    "landmark": "In the Avenue Building, second floor.", 
    "latitude": 52.1333, 
    "linkedinUrl": "https://linkedin.com/ace-plumbing", 
    "longitude": -106.6833, 
    "marketId": "market-west", 
    "paymentMethods": [
        "MasterCard", 
        "Visa", 
        "Cash", 
        "Check"
    ], 
    "pinterestUrl": "https://pinterest.com/ace-plumbing", 
    "place": "", 
    "productsJson": {
        "MS": {
            "productId": "MS-275831"
        }, 
        "RM": {
            "productId": "SR-097826"
        }, 
        "SM": {
            "productId": "AC-012345"
        }
    }, 
    "rmAdminNotes": "Admin notes test", 
    "rssUrl": "https://ace-plumbing.com/rss", 
    "salesPersonId": "SP-GH5FNWMZ", 
    "servicesOffered": [
        "Plumbing", 
        "pipe clearing", 
        "installation"
    ], 
    "shareOfVoiceService": [], 
    "shortDescription": "We do plumber things!", 
    "socialProfileId": "SCP-9E6301BA27CC4F628A33DEDB739C4141", 
    "state": "SK", 
    "tag": [
        "PlumberConf 2016"
    ], 
    "tagline": "Professional, affordable - and we always leave the seat down!", 
    "taxonomyId": [
        "localservices"
    ], 
    "tollFreeNumber": "18005551234", 
    "twitterUrl": "https://twitter.com/ace-plumbing", 
    "updated": "2013-06-06T19:36:36Z", 
    "website": "http://www.aceplumbing.com", 
    "workNumber": [
        "3063868399"
    ], 
    "youtubeUrl": "https://youtube.com/ace-plumbing", 
    "zip": "S7K 1M1"
}

Update Account v3.0

This end-point is used to update an account.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v3/account/update/
Parameter Required? Type Multiples? Notes
SEOCategory string Search engine terms related to a business Maximum instances: 3
accountId string A unique account identifier. One of accountId or customerIdentifier must be specified.
actionLists string
address string The address of the business.
address2 string
brandsCarried string Primary brands carried. e.g. Panasonic, Apple. Total length of brands carried must be less than 256 characters, when joined with commas.
callTrackingNumber string A list of call tracking numbers. Maximum instances: 3
cellNumber string The cell number for a business
city string The city of the business.
commonName string A common name for a business (Something it is often referred to as) Maximum instances: 3
companyName string A descriptive company name.
competitor string Competitors for a business
contactEmail string The email for someone at the business. If this is provided, it will create a Business App user using contactFirstName, contactLastName and contactPhoneNumber.
contactFirstName string The first name for a contact for a business
contactLastName string The last name for a contact for a business
contactPhoneNumber string The phone number to contact someone at a business
country string The 2-letter country code.
customerIdentifier string A unique identifier. One of accountId or customerIdentifier must be specified.
description string Maximum length: 1000
email string The email for a business
facebookUrl string The fully qualified URL of a Facebook page.
faxNumber string The fax number for a business
foursquareUrl string The fully qualified URL of a FourSquare user.
googleplusUrl string The fully qualified URL of a Google+ page.
healthCareProfessionalInformationJson JSON (see description) Information for a health care professional. Should be supplied as a json dict. (See example response.) Validates all fields passed in.
hoursOfOperationJson JSON (see description) Hours of operation for a business. Should be supplied as a json dict. (See example response.)
instagramUrl string The exact instagram url for a business
keyPerson string A key person for a business Maximum instances: 3
landmark string Reference to the general area of the business. e.g. Downtown Mall. Maximum length: 60
latitude float A float on [-90.0, 90.0]. If specified, longitude must also be specified. Value must be [-90.0, 90.0].
linkedinUrl string The fully qualified URL of a LinkedIn user.
longitude float A float on [-180.0, 180.0]. If specified, latitude must also be specified. Value must be [-180.0, 180.0].
marketId string A valid marketId for this Partner. Must be lowercase letters, numbers or dashes.
paymentMethods string Possible methods: American Express, Android Pay, Apple Pay, Cash, Check, Debit, Diners Club, Discover, MasterCard, PayPal, Samsung Pay, Store Card, Travelers Checks, Visa Payment methods must be one of a set of defined values
pinterestUrl string The exact pinterest url for a business
place string A textual description of where a business is. ex: 'The Avenue Building'
rmAdminNotes string
rssUrl string The rss feed url for a business
salesPersonId string A unique sales person identifier.
serviceAreaBusinessFlag boolean
servicesOffered string Services offered, e.g. personal tax filing, business tax filing. Total length of services offered must be less than 256 characters, when joined with commas.
shareOfVoiceService string Share of voice services for a business Share of voice services for a business
shortDescription string Maximum length: 200
socialProfileId string A unique social profile identifier.
state string The state code.
tag string Custom tags. Maximum length: 50 Maximum instances: 15
tagline string The tagline, catchphrase or motto of a business. ex: 'I'm lovin it'.
taxonomyId string Up to 3 can be supplied, must comply with vTaxonomy Ids available from Core.
tollFreeNumber string
twitterUrl string The fully qualified URL of a Twitter user.
website string The website of the business.
workNumber string A list of work numbers Maximum instances: 6
youtubeUrl string The exact youtube url for a business
zip string The zip/postal code for the address.
Response codes

A list of potential status codes that may be returned.

201
If the account was successfully updated.
400
If invalid parameters are submitted.
404
If no partner with the specified pid exists.
409
If a socialProfileId or marketId is invalid or not registered.
500
An undefined error case
Example response

Returns the updated account information.

"data": {
    "SEOCategory": [
        "plumbing"
    ], 
    "accountId": "AG-2AA972E", 
    "actionLists": [
        "campaign X list"
    ], 
    "address": "220 3rd Ave S", 
    "address2": "Suite #405", 
    "brandsCarried": [
        "American Standard", 
        "Flush-O-Matic"
    ], 
    "callTrackingNumber": [
        "3069523875"
    ], 
    "cellNumber": "3062221234", 
    "city": "Saskatoon", 
    "commonName": [
        "Ace Plumbers"
    ], 
    "companyName": "Ace Plumbing", 
    "competitor": [
        "Gary Plumbing"
    ], 
    "contactEmail": "johndoe@example.com", 
    "contactFirstName": "John", 
    "contactLastName": "Doe", 
    "contactPhoneNumber": "1-800-267-2001", 
    "country": "CA", 
    "created": "2013-06-06T19:36:36Z", 
    "customerIdentifier": null, 
    "description": "The number 1 plumber in the greater Saskatoon area! We specialize in everything from out houses to olympic pools.", 
    "email": "office@example.com", 
    "facebookUrl": "https://facebook.com/ace-plumbing", 
    "faxNumber": "3065554444", 
    "foursquareUrl": "https://foursquare.com/ace-plumbing", 
    "googleplusUrl": "https://plus.google.com/ace-plumbing", 
    "healthCareProfessionalInformationJson": {
        "dateOfBirth": "1999-12-31", 
        "email": "smith@jonesmedical.com", 
        "fellowship": [
            "Innitech Medic Co."
        ], 
        "firstName": "Jane", 
        "gender": "Female", 
        "initials": "M", 
        "insurancesAccepted": [
            "All-Tech Insurance", 
            "Happy Acres Industrial Insurance"
        ], 
        "isTakingPatients": true, 
        "lastName": "Smith", 
        "medicalLicenseNumber": "123456789", 
        "nationalProviderIdentifier": "1111111111", 
        "office": "Jones Medical", 
        "professionalCredential": [
            "MD"
        ], 
        "residency": [
            "Houston General Oncology"
        ], 
        "school": [
            "Texas State"
        ], 
        "specialty": [
            "Oncology"
        ], 
        "standardizedTitle": "VP", 
        "stateLicense": "55555"
    }, 
    "hoursOfOperationJson": [
        {
            "closes": "18:00", 
            "dayOfWeek": [
                "Monday", 
                "Tuesday", 
                "Wednesday", 
                "Thursday", 
                "Friday"
            ], 
            "description": "Normal Weekday hours", 
            "opens": "6:00"
        }, 
        {
            "closes": "", 
            "dayOfWeek": [
                "PublicHolidays"
            ], 
            "description": "By appointment only.", 
            "opens": ""
        }
    ], 
    "instagramUrl": "https://instagram.com/ace-plumbing", 
    "keyPerson": [
        "John Doe"
    ], 
    "landmark": "In the Avenue Building, second floor.", 
    "latitude": 52.1333, 
    "linkedinUrl": "https://linkedin.com/ace-plumbing", 
    "longitude": -106.6833, 
    "marketId": "market-west", 
    "paymentMethods": [
        "MasterCard", 
        "Visa", 
        "Cash", 
        "Check"
    ], 
    "pinterestUrl": "https://pinterest.com/ace-plumbing", 
    "place": "", 
    "productsJson": {
        "MS": {
            "productId": "MS-275831"
        }, 
        "RM": {
            "productId": "SR-097826"
        }, 
        "SM": {
            "productId": "AC-012345"
        }
    }, 
    "rmAdminNotes": "Admin notes test", 
    "rssUrl": "https://ace-plumbing.com/rss", 
    "salesPersonId": "SP-GH5FNWMZ", 
    "servicesOffered": [
        "Plumbing", 
        "pipe clearing", 
        "installation"
    ], 
    "shareOfVoiceService": [], 
    "shortDescription": "We do plumber things!", 
    "socialProfileId": "SCP-9E6301BA27CC4F628A33DEDB739C4141", 
    "state": "SK", 
    "tag": [
        "PlumberConf 2016"
    ], 
    "tagline": "Professional, affordable - and we always leave the seat down!", 
    "taxonomyId": [
        "localservices"
    ], 
    "tollFreeNumber": "18005551234", 
    "twitterUrl": "https://twitter.com/ace-plumbing", 
    "updated": "2013-06-06T19:36:36Z", 
    "website": "http://www.aceplumbing.com", 
    "workNumber": [
        "3063868399"
    ], 
    "youtubeUrl": "https://youtube.com/ace-plumbing", 
    "zip": "S7K 1M1"
}

Delete Account v3.0

This end-point is used to delete an account.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v3/account/delete/
Parameter Required? Type Multiples? Notes
accountId string A unique account identifier.
Response codes

A list of potential status codes that may be returned.

200
If the account was successfully deleted.
404
If no account exists.
500
An undefined error case
Example response

Returns the deleted account with a deleted date.

"data": {
    "accountId": "AG-2AA972E"
}

Get Account v3.0

This end-point is used to get an account given an accountId or customerIdentifier.

  • Rate limit: 300/minute 
GET https://business-center-api.vendasta.com/api/v3/account/get/
Parameter Required? Type Multiples? Notes
accountId string A unique account identifier. One of accountId or customerIdentifier must be specified.
customerIdentifier string A unique identifier. One of accountId or customerIdentifier must be specified.
Response codes

A list of potential status codes that may be returned.

201
If the account was successfully created.
400
If invalid parameters are submitted.
404
If no account with the specified accountGroupId or customerIdentifier exists.
409
If a socialProfileId or marketId is invalid or not registered.
500
An undefined error case
Example response

Returns the account information.

"data": {
    "SEOCategory": [
        "plumbing"
    ], 
    "accountId": "AG-2AA972E", 
    "actionLists": [
        "campaign X list"
    ], 
    "address": "220 3rd Ave S", 
    "address2": "Suite #405", 
    "brandsCarried": [
        "American Standard", 
        "Flush-O-Matic"
    ], 
    "callTrackingNumber": [
        "3069523875"
    ], 
    "cellNumber": "3062221234", 
    "city": "Saskatoon", 
    "commonName": [
        "Ace Plumbers"
    ], 
    "companyName": "Ace Plumbing", 
    "competitor": [
        "Gary Plumbing"
    ], 
    "contactEmail": "johndoe@example.com", 
    "contactFirstName": "John", 
    "contactLastName": "Doe", 
    "contactPhoneNumber": "1-800-267-2001", 
    "country": "CA", 
    "created": "2013-06-06T19:36:36Z", 
    "customerIdentifier": null, 
    "description": "The number 1 plumber in the greater Saskatoon area! We specialize in everything from out houses to olympic pools.", 
    "email": "office@example.com", 
    "facebookUrl": "https://facebook.com/ace-plumbing", 
    "faxNumber": "3065554444", 
    "foursquareUrl": "https://foursquare.com/ace-plumbing", 
    "googleplusUrl": "https://plus.google.com/ace-plumbing", 
    "healthCareProfessionalInformationJson": {
        "dateOfBirth": "1999-12-31", 
        "email": "smith@jonesmedical.com", 
        "fellowship": [
            "Innitech Medic Co."
        ], 
        "firstName": "Jane", 
        "gender": "Female", 
        "initials": "M", 
        "insurancesAccepted": [
            "All-Tech Insurance", 
            "Happy Acres Industrial Insurance"
        ], 
        "isTakingPatients": true, 
        "lastName": "Smith", 
        "medicalLicenseNumber": "123456789", 
        "nationalProviderIdentifier": "1111111111", 
        "office": "Jones Medical", 
        "professionalCredential": [
            "MD"
        ], 
        "residency": [
            "Houston General Oncology"
        ], 
        "school": [
            "Texas State"
        ], 
        "specialty": [
            "Oncology"
        ], 
        "standardizedTitle": "VP", 
        "stateLicense": "55555"
    }, 
    "hoursOfOperationJson": [
        {
            "closes": "18:00", 
            "dayOfWeek": [
                "Monday", 
                "Tuesday", 
                "Wednesday", 
                "Thursday", 
                "Friday"
            ], 
            "description": "Normal Weekday hours", 
            "opens": "6:00"
        }, 
        {
            "closes": "", 
            "dayOfWeek": [
                "PublicHolidays"
            ], 
            "description": "By appointment only.", 
            "opens": ""
        }
    ], 
    "instagramUrl": "https://instagram.com/ace-plumbing", 
    "keyPerson": [
        "John Doe"
    ], 
    "landmark": "In the Avenue Building, second floor.", 
    "latitude": 52.1333, 
    "linkedinUrl": "https://linkedin.com/ace-plumbing", 
    "longitude": -106.6833, 
    "marketId": "market-west", 
    "paymentMethods": [
        "MasterCard", 
        "Visa", 
        "Cash", 
        "Check"
    ], 
    "pinterestUrl": "https://pinterest.com/ace-plumbing", 
    "place": "", 
    "productsJson": {
        "MS": {
            "productId": "MS-275831"
        }, 
        "RM": {
            "productId": "SR-097826"
        }, 
        "SM": {
            "productId": "AC-012345"
        }
    }, 
    "rmAdminNotes": "Admin notes test", 
    "rssUrl": "https://ace-plumbing.com/rss", 
    "salesPersonId": "SP-GH5FNWMZ", 
    "servicesOffered": [
        "Plumbing", 
        "pipe clearing", 
        "installation"
    ], 
    "shareOfVoiceService": [], 
    "shortDescription": "We do plumber things!", 
    "socialProfileId": "SCP-9E6301BA27CC4F628A33DEDB739C4141", 
    "state": "SK", 
    "tag": [
        "PlumberConf 2016"
    ], 
    "tagline": "Professional, affordable - and we always leave the seat down!", 
    "taxonomyId": [
        "localservices"
    ], 
    "tollFreeNumber": "18005551234", 
    "twitterUrl": "https://twitter.com/ace-plumbing", 
    "updated": "2013-06-06T19:36:36Z", 
    "website": "http://www.aceplumbing.com", 
    "workNumber": [
        "3063868399"
    ], 
    "youtubeUrl": "https://youtube.com/ace-plumbing", 
    "zip": "S7K 1M1"
}

Search Account v3.0

This end-point is used to search for an account.

  • Rate limit: 300/minute
  • Supports paged results nextUrl
GET https://business-center-api.vendasta.com/api/v3/account/search/
Parameter Required? Type Multiples? Notes
cursor string
includeMSFlag boolean Indicate whether or not to include accounts with a paid listing builder product.
includeMSInactiveFlag boolean Indicate whether or not to include accounts without a listing builder product. This is exclusive with the listing builder inclusion flag.
includeRMDemoFlag boolean Indicate whether or not to include account with a demo reputation product.
includeRMFlag boolean Indicate whether or not to include accounts with a reputation product.
includeRMInactiveFlag boolean Indicate whether or not to include accounts without a reputation product. This is exclusive with the other reputation inclusion flags.
includeSMFlag boolean Indicate whether or not to include account with a paid social product.
includeSMInactiveFlag boolean Indicate whether or not to include accounts without a social product. This is exclusive with the social inclusion flag.
marketId string A valid marketId for this Partner. Must be lowercase letters, numbers or dashes.
orderBy string Indicate which field to sort by. Must be one of created, updated OrderBy must be one of a set of defined values.
orderByDirection string Indicate which direction to sort in. Must be one of desc, asc OrderByDirection must be one of a set of defined values.
productId string
salesPersonId string A unique sales person identifier.
searchTerm string
DEPRECATED: This argument can be provided but will have no effect on the query.
pageSize int Must be a positive integer.
Response codes

Potential status codes

200
Successfully retrieved the Account
400
Invalid or missing parameters.
404
Unable to find partner by given pid.
Example response

Returns a list of Accounts matching the search criteria.

"data": [
    {
        "accountId": "AG-2AA972E", 
        "actionLists": [
            "campaign X list"
        ], 
        "address": "220 3rd Ave S", 
        "callTrackingNumber": [
            "3069523875"
        ], 
        "city": "Saskatoon", 
        "companyName": "Ace Plumbing", 
        "country": "CA", 
        "created": "2013-06-06T19:36:36Z", 
        "customerIdentifier": null, 
        "facebookUrl": "https://facebook.com/ace-plumbing", 
        "foursquareUrl": "https://foursquare.com/ace-plumbing", 
        "googleplusUrl": "https://plus.google.com/ace-plumbing", 
        "latitude": 52.1333, 
        "linkedinUrl": "https://linkedin.com/ace-plumbing", 
        "longitude": -106.6833, 
        "marketId": [
            "market-west"
        ], 
        "productId": [
            "MP-123"
        ], 
        "productsJson": {
            "MS": {
                "productId": "MS-65789"
            }, 
            "RM": {
                "productId": "SR-097826"
            }, 
            "SM": {
                "productId": "AC-012345"
            }
        }, 
        "salesPersonId": "SP-GH5FNWMZ", 
        "socialProfileId": "SCP-9E6301BA27CC4F628A33DEDB739C4141", 
        "state": "SK", 
        "tag": [
            "PlumberConf 2016"
        ], 
        "taxonomyId": [
            "localservices"
        ], 
        "twitterUrl": "https://twitter.com/ace-plumbing", 
        "updated": "2013-06-06T19:36:36Z", 
        "website": "http://www.aceplumbing.com", 
        "workNumber": [
            "3063868399"
        ], 
        "zip": "S7K 1M1"
    }
]

Add New Product to Account v3.0

This end-point is used to add a new product to an account.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v3/account/addProduct/
Parameter Required? Type Multiples? Notes
accountId string A unique account identifier.
productId string A unique product identifier. Must be one of: RM, MS, SM.
isDemoFlag boolean A boolean flag to indicate whether the given account should be created as a trial account. May only be provided for the RM product. Default: false
Response codes

A list of potential status codes that may be returned.

200
If the product was successfully added to the account
400
If invalid parameters are submitted
404
If the specified account id cannot be found
409
If the specified product already exists for the given account
500
If an unknown error occurs
Example response

Returns the account and its updated set of products.

"data": {
    "accountId": "AG-2AA972E", 
    "actionLists": [
        "campaign X list"
    ], 
    "address": "220 3rd Ave S", 
    "callTrackingNumber": [
        "3069523875"
    ], 
    "city": "Saskatoon", 
    "companyName": "Ace Plumbing", 
    "country": "CA", 
    "created": "2013-06-06T19:36:36Z", 
    "customerIdentifier": null, 
    "facebookUrl": "https://facebook.com/ace-plumbing", 
    "foursquareUrl": "https://foursquare.com/ace-plumbing", 
    "googleplusUrl": "https://plus.google.com/ace-plumbing", 
    "latitude": 52.1333, 
    "linkedinUrl": "https://linkedin.com/ace-plumbing", 
    "longitude": -106.6833, 
    "marketId": "market-west", 
    "productsJson": {
        "MS": {
            "productId": "MS-65789"
        }, 
        "RM": {
            "productId": "SR-097826"
        }, 
        "SM": {
            "productId": "AC-012345"
        }
    }, 
    "salesPersonId": "SP-GH5FNWMZ", 
    "socialProfileId": "SCP-9E6301BA27CC4F628A33DEDB739C4141", 
    "state": "SK", 
    "tag": [
        "PlumberConf 2016"
    ], 
    "taxonomyId": [
        "localservices"
    ], 
    "twitterUrl": "https://twitter.com/ace-plumbing", 
    "updated": "2013-06-06T19:36:36Z", 
    "website": "http://www.aceplumbing.com", 
    "workNumber": [
        "3063868399"
    ], 
    "zip": "S7K 1M1"
}

Product Associations

These end-points are used for accessing Business Center Association details.

Remove a Business Center Association v2.0

Removes an assocation from the datastore.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/userAssociation/remove/
Parameter Required? Type Multiples? Notes
associationId string A key for the association that should be removed
userId string The user_id of the user who should be un-associated
Response codes

A list of potential status codes that may be returned.

200
If the association was successfully removed
400
If any of the required parameters are missing, or the key could not be deleted. The error message will be in json format and detail what the issue is.
404
If the association was not found.
405
If the api is called via a POST
500
In any other undefined error case

Create Business Center Associations v2.0

This end-point is used to create associations given a Business Center user id.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/userAssociation/create/
Parameter Required? Type Multiples? Notes
accountId string A unique account identifier.
productId string A unique product identifier.
userId string A unique user id.
Response codes

A list of potential status codes that may be returned.

200
If the key was successfully associated
403
If the PID and User ID do not match
404
If the user is not found, or a matching account is not found
500
If an unknown error occurs
Example response

Returns the association key created

"data": {
    "associationId": "UID-RGHDJ3ML-HH8JH8L8-RM"
}

Lookup Business Center Associations v2.2

This end-point is used to lookup all associations given a Business Center user id.

  • Rate limit: 300/minute 
GET https://business-center-api.vendasta.com/api/v2/userAssociation/lookup/
Parameter Required? Type Multiples? Notes
userId string The Business Center user id used to retrieve associations.
cursor string
includeLabelsFlag boolean
pageSize integer
productId string
Response codes

A list of potential status codes that may be returned.

200
If the users were successfully found and returned
405
If the api is called via a POST
500
In any other undefined error case
Example response

Returns a list of associations

"data": [
    {
        "associations": [
            {
                "accountId": "ABC|Fort Healthcare 2", 
                "associationId": "UID-CMZ674KB-ABC|FORT HEALTHCARE 2-NB", 
                "label": "Fort Healthcare 2"
            }, 
            {
                "accountId": "ABC|Fort Healthcare", 
                "associationId": "UID-CMZ674KB-ABC|FORT HEALTHCARE-NB", 
                "label": "Fort Healthcare"
            }
        ], 
        "productId": "NB"
    }, 
    {
        "associations": [
            {
                "accountId": "AG-CBF39V64", 
                "associationId": "UID-CMZ674KB-AG-CBF39V64-AGID", 
                "label": {
                    "accounts": [
                        {
                            "accountId": "MS-FNT3ZFH8", 
                            "productId": "MS", 
                            "tags": [
                                "trial"
                            ]
                        }, 
                        {
                            "accountId": "ZTTSG5CQ", 
                            "productId": "RM", 
                            "tags": []
                        }, 
                        {
                            "accountId": "AC-ZK35M5QC", 
                            "productId": "SM", 
                            "tags": []
                        }
                    ], 
                    "name": "Mainway Mazda"
                }
            }
        ], 
        "productId": "AGID"
    }
]

Remove All Associations For A Business Center Product v2.0

Removes all the associations for a given product id.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/productAssociation/remove/
Parameter Required? Type Multiples? Notes
accountId string The product specific account id.
productId string A key identifying the product for which this association is for.
Response codes

A list of potential status codes that may be returned.

200
If the system has accepted the request and is trying to remove the associations for this product id. It will also return 200 if there are no associations that need to be removed.
400
If any of the required parameters are missing. The response will be in json format and detail what the issue is.
405
If the api is called via a GET
500
In any other undefined error case
Example response

Returns a list of association keys that were removed.

"data": [
    {
        "associationId": "UID-RGHDJ3ML-HH8JH8L8-RM"
    }, 
    {
        "associationId": "UID-F9FK4XZL-HH8JH8L8-RM"
    }
]

Users

These end-points are used for accessing and modifying Business Center user details.

Search User v3.0

Search users for the given search term. Note, if the intended use is to perform an enumeration of all users please refer to the lookup api.

  • Supports paged results nextUrl
GET https://business-center-api.vendasta.com/api/v3/user/search/
Parameter Required? Type Multiples? Notes
fieldMask string A field mask that will filter the fields sent back for each user
orderBy string The order in which to return results.
orderByDirection string ASCENDING or DESCENDING
query string The search term to query for.
pageSize int Must be a positive integer.
Response codes

A list of potential status codes that may be returned.

200
If the users were successfully found and returned.
405
The resource is accessed via HTTP POST. HTTP GET is required.
500
An undefined error case.
Example response

A list of VBC users. Passwords are not returned.

"data": [
    {
        "createdDateTime": "2016-12-12T20:03:39Z", 
        "email": "userone@theinternets.com", 
        "firstName": "Lorem", 
        "lastName": "Ipsum", 
        "phoneNumber": "555-555-5555", 
        "updatedDateTime": "2016-12-12T20:03:39Z", 
        "userId": "UID-1234"
    }, 
    {
        "createdDateTime": "2016-12-12T20:03:01Z", 
        "email": "usertwo@theinternets.com", 
        "firstName": "Aliquam", 
        "lastName": "Pellentesque", 
        "phoneNumber": "555-555-5555", 
        "updatedDateTime": "2016-12-12T20:03:01Z", 
        "userId": "UID-1234"
    }
]

Lookup All Users v3.0

Lookup all users.

  • Supports paged results nextUrl
POST/GET https://business-center-api.vendasta.com/api/v3/user/lookup/
Parameter Required? Type Multiples? Notes
pageSize int Must be a positive integer.
Example response

A paginated list of VBC users. Passwords are not returned.

"data": [
    {
        "createdDateTime": "2015-02-17T17:19:06Z", 
        "email": "userone@theinternets.com", 
        "firstName": "Lorem", 
        "lastName": "Ipsum", 
        "phoneNumber": "555-555-5555", 
        "updatedDateTime": "2015-02-17T17:19:06Z", 
        "userId": "UID-1234"
    }, 
    {
        "createdDateTime": "2015-02-17T17:19:06Z", 
        "email": "usertwo@theinternets.com", 
        "firstName": "Aliquam", 
        "lastName": "Pellentesque", 
        "phoneNumber": "555-555-5555", 
        "updatedDateTime": "2015-02-17T17:19:06Z", 
        "userId": "UID-2345"
    }
]

Create And Associate Handler v3.0

Bare handler for common functions for our create and associate endpoints 

POST/GET https://business-center-api.vendasta.com
Parameter Required? Type Multiples? Notes
None

Retrieve a Business Center User v2.0

This end-point is used to retrieve Business Center users.

  • Rate limit: 300/minute 
GET https://business-center-api.vendasta.com/api/v2/user/get/
Parameter Required? Type Multiples? Notes
userId string A unique user id.
Response codes

A list of potential status codes that may be returned.

200
If the user was successfully found and returned.
400
If any of the required parameters are invalid.
403
The resource is accessed over HTTP. HTTPS is required.
405
The resource is accessed via HTTP POST. HTTP GET is required.
500
An undefined error case.
Example response

The user information corresponding to the requested user id. Passwords are not returned.

"data": {
    "email": "test@example.com", 
    "firstName": "Lorem", 
    "lastName": "Ipsum", 
    "phone": "123456789", 
    "userId": "UID-ABC123"
}

Delete a Business Center User v2.0

This end-point is used to update existing Business Center users.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/user/delete/
Parameter Required? Type Multiples? Notes
userId string A unique user id.
Response codes

A list of potential status codes that may be returned.

200
If the user was successfully found and deleted.
400
If any of the required parameters are invalid.
403
The resource is accessed over HTTP. HTTPS is required.
405
The resource is accessed via HTTP GET. HTTP POST is required.
500
An undefined error case.
Example response

A notification that the user has been deleted.

"data": The user UID-LNXMFNW9 has been deleted

Update a Business Center User v2.0

This end-point is used to update existing Business Center users.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/user/update/
Parameter Required? Type Multiples? Notes
userId string A unique user id.
confirmPassword string The users login password repeated for confirmation.
email string The email for a business
firstName string The users first name.
greetingName string The users greeting name.
lastName string The users last name.
password string The users login password.
phone string A North American phone number. Must be at least 7 digits.
preferredLocale string A locale code in IETF Language Tag standard.
Response codes

A list of potential status codes that may be returned.

200
If the user was successfully found and updated.
400
If any of the required parameters are invalid.
403
The resource is accessed over HTTP. HTTPS is required.
404
The user could not be found.
405
The resource is accessed via HTTP GET. HTTP POST is required.
500
An undefined error case.
Example response

The user information corresponding to the user id that has been updated. Passwords are not returned.

"data": {
    "email": "test@example.com", 
    "firstName": "Lorem", 
    "greetingName": "Bacon", 
    "lastName": "Ipsum", 
    "phone": "123456789", 
    "userId": "UID-ABC123"
}

Create Business Center Users v2.2

This end-point is used to create Business Center users.

Version 2.1: "password" and "confirm_password" are now optional.

Version 2.2: "password" and "confirm_password" are unused and have no effect. The user must choose their own password, by clicking the link in the welcome email or by doing a password reset.

  • Rate limit: 300/minute 
POST https://business-center-api.vendasta.com/api/v2/user/create/
Parameter Required? Type Multiples? Notes
email string The email for a business email must be valid.
confirmPassword string The value of this field is ignored and has no effect. The user can set a password via the Welcome E-mail or a password reset.
firstName string The users first name.
greetingName string The users greeting name.
lastName string The users last name.
password string The value of this field is ignored and has no effect. The user can set a password via the Welcome E-mail or a password reset.
phone string A North American phone number. Must be at least 7 digits.
preferredLocale string A locale code in IETF Language Tag standard.
sendWelcomeEmailFlag boolean Defaults to True. Supply as False if you do not want to send the user a welcome email.
welcomeMessage string A customized welcome message added to the welcome email for this user.
Response codes

A list of potential status codes that may be returned.

201
If the user was successfully created.
400
If any of the required parameters are missing or a user with the provided email already exists.
403
The resource is accessed over HTTP. HTTPS is required.
405
The resource is accessed via HTTP GET. HTTP POST is required.
500
An undefined error case.
Example response

The newly created user object containing the user id. Passwords are not returned.

"data": {
    "email": "test@example.com", 
    "firstName": "Lorem", 
    "greetingName": "Bacon", 
    "lastName": "Ipsum", 
    "phone": "123456789", 
    "userId": "UID-ABC123"
}

Deprecated Endpoints

The following endpoints are deprecated. Alternate endpoints should be used because these endpoints will stop being supported in the future.

Product Associations

These end-points are used for accessing Business Center Association details.

Get Business Center Associations v2.0

DEPRECATED

GetAssociationApi is deprecated. Please use /api/v2/userAssociation/lookup/ instead.

This end-point is used to get associations given a Business Center user id.

  • Rate limit: 300/minute 
GET https://business-center-api.vendasta.com/api/v2/association/get/
Parameter Required? Type Multiples? Notes
userId string The Business Center user id used to retrieve associations.