openapi: 3.2.0
info:
title: Customer Voice REST Templates API
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
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
tags:
- name: Templates
paths:
/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`\n\nUsed to create a new template within Customer Voice. Dynamic content can be inserted via substitution variables. \n\nThe follow variables are supported within an email template:\n\n- `{{.customerName}}`: The first and last name of the customer.\n- `{{.customerFirstName}}`: The first name of the customer.\n- `{{.businessName}}`: The business location name.\n- `{{.buttonUrl}}`: The review request button URL.\n\nCan be used for dynamic content visibility within an email template:\n\n- `{{.displaySource1}}`: Whether or not to display source 1.\n- `{{.displaySource2}}`: Whether or not to display source 2.\n- `{{.displaySource3}}`: Whether or not to display source 3.\n\nUsed to render images within an email template:\n\n- `![](\"https://www.cdnstyles.com/static/images/icon50/sourceId-{{.sourceId1}}.png\")
`\n- `![](\"https://www.cdnstyles.com/static/images/icon50/sourceId-{{.sourceId2}}.png\")
`\n- `![](\"https://www.cdnstyles.com/static/images/icon50/sourceId-{{.sourceId3}}.png\")
`\n\nUsed to render links within an email template: \n\n- `{{.sourceName1}}`\n- `{{.sourceName2}}`\n- `{{.sourceName3}}`\n\nThe following members must be populated during creation:\n- `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}},
Thank you for your business! We''d love to know more about your latest experience with us.
{{.buttonUrl}}
Thank you,
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:
- Templates
/reviewRequestTemplates/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
security:
- OAuth2Demo:
- reviews
- OAuth2Prod:
- reviews
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
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
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
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
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:
- Templates
components:
schemas:
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}},
Thank you for your business! We''d love to know more about your latest experience with us.
{{.buttonUrl}}
Thank you,
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}},
Thank you for your business! We''d love to know more about your latest experience with us.
{{.buttonUrl}}
Thank you,
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
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