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
