Sales Account

Status: Trusted Tester

A Sales Account is used by partners to track their interactions with a Business Location. It contains the public data of a business location plus additional data which is private to the partner.

idstring

Example: AG-1234567

typestring

Possible values: [salesAccounts]

Default value: salesAccounts

attributes object

tagsstring[]

A tag is a label that can be used for grouping and filtering your list of accounts. They may be any string upto 30 characters in length. There is a limit of 15 tags.

Possible values: <= 15

customerIdentifierstring

A value assigned by the business partner to reference this business location. Customer ID is currently NOT enforced to be unique, and there may be negative side effects to having a duplicate and/or changing a customer ID, specifically around legacy SSO. Use caution when editing a customer ID.

namestring

The common name for this location.

Note: The pipe character (|) is not allowed.

Possible values: non-empty, Value must match regular expression ^[^|]+$

Example: CN Tower

commonNamesstring[]

A common name for a business (Something it is often referred to as)

Possible values: <= 3

address object

line1string

The primary information. Typically a street address.

Example: 290 Bremner Blvd

line2string

An additional line of information to add after the street address.

citystring

Example: Toronto

postalCodestring

The zip code or postal code component of an address.

Example: M5V 3L9

regionCodestring

The code for the top level subdivision within the country (state/province). For more info see the Addresses guide

Examples: CA-SK, US-FL, AG-08, AU-NSW

Possible values: >= 4 characters and <= 6 characters, Value must match regular expression ^[A-Z]{2}-[\w]{1,3}$

Example: CA-ON

countryCodestring

The two letter country code. For more info see the Addresses guide

Examples: CA, US, AU

Possible values: >= 2 characters and <= 2 characters, Value must match regular expression ^[A-Z]{2}$

Example: CA

phoneNumbersstring[]

The standard phone numbers for the location. Formatting characters may be included.

Extensions

It is recommended that extensions are included at the end of the number after an appropriate separator: Pause: , Wait: ; Default: ext.

You may test the parsibility of a number using https://phonenumbers.temba.io/ All phone numbers are assumed to be in the same country as this business location.

Possible values: <= 3

serviceAreaBusinessboolean

When true the address will be used as the center of the area that this location services instead of being displayed.

geoCoordinate object

The point where the map pin for the location should be displayed.

The values will not be automatically updated when the address is updated. If not provided when creating the location they will be initialized based on the address.

It is expressed as a pair of numbers to represent degrees latitude and degrees longitude in accordance with the WGS84 standard (the one used by your GPS).

latitudenumberrequired

Possible values: >= -90 and <= 90

Example: 43.6425662

longitudenumberrequired

Possible values: >= -180 and <= 180

Example: -79.3870568

seoKeywordsstring[]deprecated

Deprecated - SEO keywords must be set in the Local SEO product

Possible values: <= 3

websiteuri

The primary website for this business location. http:// will be automatically added if no schema is provided.

Example: https://www.vendasta.com

servicesOfferedstring[]

The primary services that the business offers. For example personal tax filing, business tax filing.

Total length of services offered must be less than 256 characters, when joined with commas. Maximum instances: 15

Possible values: <= 15

descriptionShortstring

A public summary of the business. See also descriptionLong

Possible values: <= 200 characters

descriptionLongstring

A public summary of the business. See also descriptionShort

Possible values: <= 750 characters

hours object[]nullable

The operating hours for the business location. Each entry in the array is a set of hours for a particular department or customer of the business. It is recommended to provide the general hours for all locations. Some locations may have additional definitions for other departments.

Array [

hoursTypeIdstringrequired

The category of hours that may apply to a specific department or service. Not all types are valid for all business categories.

The general hours for a location must be set before defining hours for other departments.

Currently only general is supported in the Vendasta platform. We intend to add others in the future.

Possible values: [general, delivery, kitchen, driveThrough, pickup, takeout]

regularHours object[]nullable

A collection of times that this location is open for business. Each period represents a range of hours when the location is open during the week.

You may specify multiple entries for the same date if you are open for multiple periods (Example lunch and supper).

Array [

openDaya day of the weekrequired

Indicates the day of the week that this period starts on.

Possible values: [monday, tuesday, wednesday, thursday, friday, saturday, sunday]

Example: wednesday

closeDaya day of the weekrequired

Indicates the day of the week that this period ends on. It should be the same as openDay except when the period goes over midnight. The total period may not be more than 24 hours.

Possible values: [monday, tuesday, wednesday, thursday, friday, saturday, sunday]

Example: wednesday

openTimea time of dayrequired

Valid values are 00:00-24:00, where 24:00 represents midnight at the end of the specified day field.

Possible values: Value must match regular expression ^\d{2}:\d{2}$

Example: 09:45

closeTimea time of dayrequired

Valid values are 00:00-24:00, where 24:00 represents midnight at the end of the specified day field.

Possible values: Value must match regular expression ^\d{2}:\d{2}$

Example: 09:45

]

specialHours object[]nullable

Represents a set of time periods when a location's operational hours differ from its regular business hours. This may be a holiday or special event. These hours replace the regular hours for the day.

A special hour period must represent a range of less than 24 hours. The openTime and startDate must predate the closeTime and endDate. The closeTime and endDate can extend to 11:59 a.m. on the day after the specified startDate.

Note: Most listing sites only support special hours for the general type.

Array [

statusstring

Describes the different modes that apply to special hour periods. Currently only open and closed are supported in the Vendasta platform. Overlapping open and closed periods are not allowed. When status is open, for the given business it will be open for the mentioned time period for the selected date. When status is closed, for the given business it will be closed for the selected date.

Possible values: [open, closed]

startDatedaterequired

The calendar date this special hour period starts on.

endDatedaterequired

The calendar date this special hour period ends on. If endDate field is not set, default to the date specified in startDate. If set, this field must be equal to or at most 1 day after startDate.

startTimea time of dayrequired

Valid values are 00:00-24:00, where 24:00 represents midnight at the end of the specified day field.

Possible values: Value must match regular expression ^\d{2}:\d{2}$

Example: 09:45

endTimea time of dayrequired

Valid values are 00:00-24:00, where 24:00 represents midnight at the end of the specified day field.

Possible values: Value must match regular expression ^\d{2}:\d{2}$

Example: 09:45

]

]

updatedAtstring

The time at which the sales accounts was last updated

tollFreeNumberstring

The toll free number for the business.

trackingNumbersstring[]

A call tracking number is a phone number that gathers analytics for inbound calls. Call tracking is commonly used as a method of performance assessment for marketing campaigns.

Possible values: <= 6

adminNotesstring

Administration notes for the account.

primaryOperatingLanguagestring

The primary language in which this business operates, as a BCP 47 language tag (e.g. "en", "it", "fr-CA"). Returns "en" when unset. On write, an empty or omitted value is ignored (it will not clear an existing value set via Business Profile).

Example: en

socialUrls object

The Social URLs for a Sales Account.

googleplusUrluri

The URL for a Sales Account's Google Plus page.

linkedinUrluri

The URL for a Sales Account's LinkedIn page.

foursquareUrluri

The URL for a Sales Account's Foursquare page.

xUrluri

The URL for a Sales Account's X page (formerly known as Twitter).

facebookUrluri

The URL for a Sales Account's Facebook page.

youtubeUrluri

The URL for a Sales Account's Youtube page.

instagramUrluri

The URL for a Sales Account's Instagram page.

pinterestUrluri

The URL for a Sales Account's Pinterest page.

relationships object

salesPeople object

A list of the sales people assigned to this account. The first sales person in the list will be treated as the primary sales person and given special treatment.

data object[]required

Array [

idstringrequired

The user id of a salesperson.

TestSalesAccountCustomFields_update/platform/users?filter[partner.id]=TEST&filter[email]=user@example.com`.

For more information access GET /platform/users

Possible values: Value must match regular expression ^U-

typestringrequired

Default value: users

Example: users

]

customFields object

Custom Fields relative to a sales account

data object[]required

Array [

idstringrequired

ID of custom fields, can be retrieved using custom fields endpoint

typestringrequired

Default value: customFields

Example: customFields

]

businessPartner object

A link to the organization that provides the platform to this business location.

data objectrequired

typestringrequired

Possible values: [partners]

Default value: partners

idstringrequired

Example: ABC

businessCategories object

A list of the types of business this location should be compared against. The first item on the list will be considered as the primary category. If not set during creation it will default "other".

data object[]

Possible values: <= 3

Array [

typestringrequired

Possible values: [businessCategories]

Default value: businessCategories

Example: businessCategories

idstringrequired

Example: athletic_club

]

businessMarket object

A link to the market within an organization that this business location belongs to.

data object

typestring

Possible values: [salesAccountMarket]

idstring

included object[]

During Get and List operations you may request the related resources be included by using the include query parameter. This can save you making an additional network request.

Array [

anyOf

• Sales Accounts Custom Fields
• Users
• Business Category

idstringrequired

An identifier for the parent entity, for example salesAccount (AG-1231231)

Example: AG-1231232

typestringrequired

Should always be salesAccountCustomFields

Possible values: [salesAccountCustomFields]

Default value: salesAccountCustomFields

partnerFields object[]

List of custom fields specific to the partner with a direct relationship to the sales account. To send a new value each field must have at least the fieldId and its correspondent value. For example a field of type string must have the stringValue attribute filled.

string -> stringValue

integer -> integerValue

date -> dateValue

Only the fields that you wish to modify need to be sent.

Array [

fieldIdstring

Field identifier, can be retrieved by listing the attributes

externalIdstring

Alternative field identifier, can be set on admin panel and can be retrieved by listing the attributes

fieldTypestring

Indicates which of the value fields to use to read or write the data. It can only be modified from within partner center.

string -> stringValue integer -> integerValue date -> dateValue dropdown -> dropdownValue currency -> currencyValue

Possible values: [string, integer, date, dropdown, currency]

Example: string

stringValuestring

Required when the field type is string

integerValueinteger

Required when the field type is integer

dateValuedate

Required when the field type is date

dropdownValuestring

Required when type is dropdown. The possible values can be discovered using the administration panel.

currencyValueinteger

Required when the field type is currency.

This field represents the cents (or the smallest part of the currency).

Example: USD 600.00 -> currencyValue=60000

currencyCodestring

Represents the type of currency when the field is type currency. It will be the 3 letter currency code as defined by ISO 4217

Ex: USD, CAD, AUD

Possible values: >= 3 characters and <= 3 characters

Example: USD

titlestring

The main label for the field, appearing in most user interfaces that show the value. This field is not read when setting a value.

descriptionstring

A longer text explanation of the field, it optionally appears in the UI. This field is not read when setting a value.

]

]

Sales Account

{
  "id": "AG-1234567",
  "type": "salesAccounts",
  "attributes": {
    "tags": [
      "string"
    ],
    "customerIdentifier": "string",
    "name": "CN Tower",
    "commonNames": [
      "string"
    ],
    "address": {
      "line1": "290 Bremner Blvd",
      "line2": "string",
      "city": "Toronto",
      "postalCode": "M5V 3L9",
      "regionCode": "CA-ON",
      "countryCode": "CA"
    },
    "phoneNumbers": [
      "+14168686937"
    ],
    "serviceAreaBusiness": true,
    "geoCoordinate": {
      "latitude": 43.6425662,
      "longitude": -79.3870568
    },
    "website": "https://www.vendasta.com",
    "servicesOffered": [
      "root canals"
    ],
    "descriptionShort": "string",
    "descriptionLong": "string",
    "hours": [
      {
        "hoursTypeId": "general",
        "regularHours": [
          {
            "openDay": "wednesday",
            "closeDay": "wednesday",
            "openTime": "09:45",
            "closeTime": "09:45"
          }
        ],
        "specialHours": [
          {
            "startDate": "2024-07-29",
            "endDate": "2024-07-29",
            "startTime": "09:45",
            "endTime": "09:45"
          }
        ]
      }
    ],
    "updatedAt": "string",
    "tollFreeNumber": "string",
    "trackingNumbers": [
      "string"
    ],
    "adminNotes": "string",
    "primaryOperatingLanguage": "en",
    "socialUrls": {
      "googleplusUrl": "string",
      "linkedinUrl": "string",
      "foursquareUrl": "string",
      "xUrl": "string",
      "facebookUrl": "string",
      "youtubeUrl": "string",
      "instagramUrl": "string",
      "pinterestUrl": "string"
    }
  },
  "relationships": {
    "salesPeople": {
      "data": [
        {
          "id": "string",
          "type": "users"
        }
      ]
    },
    "customFields": {
      "data": [
        {
          "id": "string",
          "type": "customFields"
        }
      ]
    },
    "businessPartner": {
      "data": {
        "type": "partners",
        "id": "ABC"
      }
    },
    "businessCategories": {
      "data": [
        {
          "type": "businessCategories",
          "id": "athletic_club"
        }
      ]
    },
    "businessMarket": {
      "data": {
        "id": "string"
      }
    }
  },
  "included": [
    {
      "id": "AG-1231232",
      "type": "salesAccountCustomFields",
      "partnerFields": [
        {
          "fieldId": "string",
          "externalId": "string",
          "fieldType": "string",
          "stringValue": "string",
          "integerValue": 0,
          "dateValue": "2024-07-29",
          "dropdownValue": "string",
          "currencyValue": 0,
          "currencyCode": "USD",
          "title": "string",
          "description": "string"
        }
      ]
    },
    {
      "type": "users",
      "id": "U-3ca38c57-7677-45d4-81e8-cd29eab91d63",
      "attributes": {
        "displayName": "Bill Smith",
        "givenName": "William",
        "familyName": "Smith",
        "greetingName": "Billy",
        "email": "bill@example.com",
        "emailVerified": false,
        "emailSet": true,
        "languageLocaleCode": "en-US",
        "phoneNumbersSet": true,
        "phoneNumbers": [
          {
            "number": "+1-306-555-1234 ext. 56",
            "typeCode": "mobile"
          }
        ],
        "address": {
          "line1": "109 8th Street E.",
          "line2": "Suite 23",
          "city": "Saskatoon",
          "postalCode": "S7M 1R3",
          "regionCode": "CA-SK",
          "countryCode": "CA"
        },
        "profileImage": "https://storage.googleapis.com/wordpress-www-vendasta/vw-wordpress/Brendan-King-1.jpg",
        "timeZone": "America/Regina",
        "createdAt": "2024-07-29T15:51:28.071Z",
        "updatedAt": "2024-07-29T15:51:28.071Z"
      },
      "relationships": {
        "partner": {
          "data": {
            "type": "partners",
            "id": "ABC"
          }
        },
        "businessLocations": {
          "data": [
            {
              "type": "businessLocations",
              "id": "AG-1234567"
            }
          ]
        },
        "platformAccess": {
          "data": [
            {
              "type": "appFeatures",
              "id": "pc:access"
            }
          ]
        }
      }
    },
    {
      "id": "AG-1234567",
      "type": "businessCategories",
      "attributes": {
        "name": "string",
        "isActive": true
      }
    }
  ]
}