Vendasta Customer Voice REST API
Customer Voice product API for sending review requests to a business location customers and managing the email/SMS templates those requests use. Scope-gated with the `reviews` OAuth2 scope.
OpenAPI Specification
openapi: 3.0.0
info:
title: Customer Voice REST APIs
version: '1.0'
description: APIs for gathering authentic reviews via email or text using Customer Voice.
servers:
- url: 'https://prod.apigateway.co/products/reviews'
description: Production
- url: 'https://demo.apigateway.co/products/reviews'
description: Demo
- url: '{local}/products/reviews'
description: Local
- url: 'http://localhost:11001/products/reviews'
description: Localhost
paths:
/reviewRequests:
post:
summary: Create Review Request
operationId: post-reviewRequests
responses:
'201':
description: Created
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequests'
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Sends an email or SMS review request using a Customer Voice template.
tags:
- Review Requests
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequests'
examples: {}
description: ''
parameters:
- schema:
type: string
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
in: header
name: Content-Type
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
required: true
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
x-lifecycle:
status: trustedTester
options:
summary: Options
operationId: options-reviewRequests
responses:
'200':
description: OK
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly.'
parameters:
- schema:
type: string
in: header
name: Authorization
required: true
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
- schema:
type: string
in: header
name: Content-Type
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
required: true
tags:
- Options
- Review Requests
/reviewRequestTemplates:
post:
summary: Create Template
operationId: post-templates
responses:
'201':
description: Created
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequestTemplates'
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Used to create a new template within Customer Voice. Dynamic content can be inserted via substitution variables.
The follow variables are supported within an email template:
- `{{.customerName}}`: The first and last name of the customer.
- `{{.customerFirstName}}`: The first name of the customer.
- `{{.businessName}}`: The business location name.
- `{{.buttonUrl}}`: The review request button URL.
Can be used for dynamic content visibility within an email template:
- `{{.displaySource1}}`: Whether or not to display source 1.
- `{{.displaySource2}}`: Whether or not to display source 2.
- `{{.displaySource3}}`: Whether or not to display source 3.
Used to render images within an email template:
- `<img style="border-radius: 50%;" src="https://www.cdnstyles.com/static/images/icon50/sourceId-{{.sourceId1}}.png">`
- `<img style="border-radius: 50%;" src="https://www.cdnstyles.com/static/images/icon50/sourceId-{{.sourceId2}}.png">`
- `<img style="border-radius: 50%;" src="https://www.cdnstyles.com/static/images/icon50/sourceId-{{.sourceId3}}.png">`
Used to render links within an email template:
- `<a href="{{.shareUrl1}}" style="text-decoration: none; color: #999999;">{{.sourceName1}}</a>`
- `<a href="{{.shareUrl2}}" style="text-decoration: none; color: #999999;">{{.sourceName2}}</a>`
- `<a href="{{.shareUrl3}}" style="text-decoration: none; color: #999999;">{{.sourceName3}}</a>`
The following members must be populated during creation:
- `relationships.businessLocation.data.id`
x-lifecycle:
status: trustedTester
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
parameters:
- schema:
type: string
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
default: application/vnd.api+json
example: application/vnd.api+json
in: header
name: Content-Type
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
required: true
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequestTemplates'
examples:
Example Email Request:
value:
data:
type: reviewRequestTemplates
attributes:
name: My Preferred Sites Review Request
content: |-
Hi {{.customerName}},
<br>
<br>
Thank you for your business! We'd love to know more about your latest experience with us.
<br>
<br>
{{.buttonUrl}}
<br>
<br>
Thank you,
<br>
John Doe
metadata:
subject: Thank you for choosing us!
replyEmail: jondoe@mail.com
languageLocaleCode: en-US
type: email
relationships:
businessLocation:
data:
id: AG-12345
Example SMS Request:
value:
data:
type: reviewRequestTemplates
attributes:
name: My Preferred Sites Review Request
content: We'd love to hear about your recent experience with us. Leave us a review here.
metadata:
customUrl: 'https://www.yourcustomerexperience.com/reviews/'
greeting: 'Hi {first_name}'
reviewType: custom
type: sms
relationships:
businessLocation:
data:
id: AG-12345
tags:
- Templates
get:
summary: List Templates
operationId: get-templates
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/reviewRequestTemplates'
links:
type: object
properties:
self:
type: string
format: uri
first:
type: string
description: Provides a link back to the first page of results
format: uri
next:
type: string
description: The URI at which the next batch of templates can be gotten from
format: uri
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Produces a list of templates
parameters:
- schema:
type: string
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
in: query
name: 'filter[businessLocation.id]'
description: Return templates for the specified business location
required: true
- schema:
type: string
in: query
description: The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
name: 'page[cursor]'
- schema:
type: string
in: query
description: The maximum number of tasks you would like returned in a single batch. Use the links.next member in the response to get the remainder. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
name: 'page[limit]'
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
tags:
- Templates
x-lifecycle:
status: trustedTester
x-internal: false
options:
summary: List valid HTTP verbs for /reviewRequestTemplates
operationId: options-templates
responses:
'204':
description: No Content
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
tags:
- Options
- Templates
'/reviewRequestTemplates/{id}':
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
summary: Get Template
tags:
- Templates
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequestTemplates'
links:
type: object
properties:
self:
type: string
operationId: get-templates-id
x-lifecycle:
status: trustedTester
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Fetch the current values for the specified template.
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
delete:
summary: Delete Template
tags:
- Templates
responses:
'204':
description: No Content
operationId: delete-templates-id
x-lifecycle:
status: trustedTester
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Delete the specified template.
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
patch:
summary: Update Template
operationId: patch-templates-id
tags:
- Templates
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Update the existing template.
Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.
x-lifecycle:
status: trustedTester
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
default: application/vnd.api+json
enum:
- application/vnd.api+json
in: header
name: Content-Type
required: true
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
responses:
'200':
description: Ok
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequestTemplates'
links:
type: object
properties:
self:
type: string
format: uri
description: The address of the updated template
headers: {}
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/reviewRequestTemplates'
options:
summary: 'List valid HTTP verbs for /reviewRequestTemplates/{id}'
operationId: options-templates-id
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
responses:
'204':
description: No Content
tags:
- Options
- Templates
components:
securitySchemes:
JWT:
type: http
scheme: bearer
bearerFormat: JWT
OAuth2Demo:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-demo.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-demo.apigateway.co/oauth2/token'
scopes:
reviews: Read-write access to review request APIs
OAuth2Prod:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-prod.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-prod.apigateway.co/oauth2/token'
scopes:
reviews: Read-write access to review request APIs
schemas:
reviewRequests:
title: reviewRequests
type: object
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
A Review Request is an instance of a business location attempting to send an email or SMS review request to a customer.
x-lifecycle:
status: trustedTester
x-tags:
- Review Requests
x-examples:
Example:
id: RQT-00003fa2-bd72-40c2-9101-xxxxxxxxxxxx
type: reviewRequests
attributes:
requestType: email
status: sending
createdAt: '2019-08-24T14:15:22Z'
updatedAt: '2019-08-24T14:15:22Z'
relationships:
customer:
data:
id: 'AG-abc123:CUSTOMER-003c26eb-f940-48c6-a5dc-xxxxxxxxxxxx'
type: customer
primaryTemplate:
data:
id: 'AG-abc123:sms:TEM-d2f4cf1aa7ae480bbf0a2da67dxxxxxx'
type: template
fallbackTemplate:
data:
id: 'AG-abc123:email:TEM-d2f4cf1aa7ae480bbf0a2da67dxxxxxx'
type: template
properties:
id:
type: string
example: RQT-00003fa2-bd72-40c2-9101-xxxxxxxxxxxx
readOnly: true
type:
type: string
default: reviewRequests
readOnly: true
attributes:
type: object
properties:
requestType:
type: string
enum:
- email
- sms
readOnly: true
status:
type: string
enum:
- sending
- sent
- opened
- clicked
- dropped
- unsubscribed
description: |-
`sending`- the initial status of a successfully created ReviewRequest.
`sent`- set when review request delivery is confirmed.
`opened`- set when an email review request has been opened.
`clicked`- set when the review site link has been clicked in a review request.
`dropped`- set when a review request delivery has failed ex. sending an SMS review request to a landline phone number.
`unsubscribed`- set when attempting to send a request to a customer that has previously unsubscribed from review requests from this business location.
readOnly: true
createdAt:
type: string
format: date-time
readOnly: true
updatedAt:
type: string
format: date-time
readOnly: true
relationships:
type: object
properties:
customer:
type: object
properties:
data:
type: object
properties:
id:
type: string
example: 'AG-abc123:CUSTOMER-003c26eb-f940-48c6-a5dc-xxxxxxxxxxxx'
maxLength: 256
description: 'Should be in the format `{{business location id}}:{{Vendasta customer id}}`. Vendasta customer ids may be in the form of `CUSTOMER-003c26eb-f940-48c6-a5dc-xxxxxxxxxxxx` or `CONTACT-003c26eb-f940-48c6-a5dc-xxxxxxxxxxxx`.'
type:
type: string
default: customer
readOnly: true
required:
- id
primaryTemplate:
type: object
properties:
data:
type: object
properties:
id:
type: string
example: 'AG-abc123:sms:TEM-d2f4cf1aa7ae480bbf0a2da67dxxxxxx'
maxLength: 256
description: 'Should be in the format `{{business location id}}:{{template type}}:{{template id}}`'
type:
type: string
default: template
readOnly: true
required:
- id
fallbackTemplate:
type: object
properties:
data:
type: object
properties:
id:
type: string
example: 'AG-abc123:email:TEM-d2f4cf1aa7ae480bbf0a2da67dxxxxxx'
maxLength: 256
description: 'Should be in the format `{{business location id}}:{{template type}}:{{template id}}`'
type:
type: string
default: template
readOnly: true
reviewRequestTemplates:
title: Templates
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Templates that can be used for emails and other messaging services.
type: object
x-examples:
Example Template:
type: reviewRequestTemplates
id: AG-12345/type/email/template-id/TEM-12345
attributes:
name: My Preferred Sites Review Request
content: |-
Hi {{.customerName}},
<br>
<br>
Thank you for your business! We'd love to know more about your latest experience with us.
<br>
<br>
{{.buttonUrl}}
<br>
<br>
Thank you,
<br>
John Doe
emailMetadata:
attributes:
subject: Thank you for choosing us!
replyEmail: jondoe@mail.com
languageLocaleCode: en-US
type: email
relationships:
businessLocation:
data:
id: AG-12345
x-lifecycle:
status: trustedTester
x-tags:
- Templates
properties:
id:
type: string
example: AG-12345/type/email/template-id/TEM-12345
readOnly: true
type:
type: string
default: reviewRequestTemplates
enum:
- reviewRequestTemplates
readOnly: true
attributes:
type: object
properties:
name:
type: string
description: A user friendly description for the template.
example: My Preferred Sites Review Request
emailMetadata:
type: object
description: Additional information about the template.
properties:
subject:
type: string
description: The subject line of the email.
example: Thank you for choosing us!
replyTo:
type: string
description: The email address to which the customer should reply.
example: jondoe@mail.com
format: email
smsMetadata:
type: object
description: Additional information about the template.
properties:
url:
type: string
description: The url that will customer will be sent to.
example: 'https://www.yoursite.com/reviews/customer-123'
format: uri
greeting:
type: string
description: 'The sms message prefix. `{first_name}` is an optional template variable that can be used within the greeting.'
example: 'Hi {first_name}'
prefix:
type: string
description: Generally a shortened version of the company name.
templateType:
type: string
enum:
- myListing
- preferredReviewSites
- custom
description: |-
- `myListing`: The link within the sms message will direct the customer to the my listing page.
- `preferredReviewSites`: The link within the sms message will direct the customer to the preferred review sites.
- `custom`: The link within the sms message will direct the customer to the custom url configured within the metadata.
content:
type: string
description: The content of the template.
example: |-
Hi {{.customerName}},
<br>
<br>
Thank you for your business! We'd love to know more about your latest experience with us.
<br>
<br>
{{.buttonUrl}}
<br>
<br>
Thank you,
<br>
John Doe
languageLocaleCode:
type: string
pattern: '^[a-z]{2}-[A-Z]{2}$'
example: en-US
description: |-
The local language that the template was written in.
Note: We currently have a limited set of allowed languages but expect to support many more in the future. When the requested language is not supported US English will be used.
It should be a single BCP47/RFC5646 language tag. This is an [ISO 639-1 Alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code in lowercase and an [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code in uppercase, separated by a dash.
Examples:
- `en-US` English (US)
- `fr-FR` French (France)
templateType:
type: string
enum:
- email
- sms
description: The type of the template.
example: email
relationships:
type: object
properties:
businessLocation:
type: object
properties:
data:
type: object
properties:
id:
type: string
minLength: 1
description: The ID of the business location the template belongs to.
type:
type: string
default: businessLocation
enum:
- businessLocation
readOnly: true
required:
- id
tags:
- name: Review Requests
- name: Templates
- name: Options
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews