# This is a swagger.io definition for the SaaSquatch Rest API
swagger: "2.0"
info:
  title: SaaSquatch REST API Reference
  description: |
    The SaaSquatch API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

    To make the SaaSquatch API as explorable as possible, accounts have test-mode API keys as well as live-mode API keys. These keys are both active at the same time. Data created with test-mode credentials will use your payment system's respective test mode.
  version: 1.0.0
# the domain of the service
host: app.referralsaasquatch.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /api/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  ## Describes API Key used as the Basic password approach
  APIKey:
    type: basic
    description: Authorize your requests using a tenant's API Key. Use this method of security only in server-to-server interactions.
  ## Describes the method of using JWT tokens for the Open API
  UserJWT:
    type: apiKey
    in: header
    name: X-SaaSquatch-User-Token
    description: Authorize your requests using a JWT (JSON Web Token) for a given user. Useful for client-server authorization, such as the Mobile and Web SDKs. Used in Open Endpoints.
    x-scopes:
      - read
      - write
externalDocs:
  description: "Official SaaSquatch documentation"
  url: "http://docs.referralsaasquatch.com/api"
parameters:
  tenant_alias:
    name: tenant_alias
    in: path
    description: |
      Tenant being referenced. E.g. `"aboih12h16t"` or `"test_abo912126tastastt"`
    type: string
    required: true
  limit:
    name: limit
    in: query
    type: integer
    description: "A limit on the number of results returned. Defaults to `10`."
    default: 10
  offset:
    name: offset
    in: query
    type: integer
    description: "When included offsets the first result returns in the list. Use this to paginate through a long list of results. Defaults to `0`"
    default: 0
  fields:
    name: fields
    in: query
    type: string
    required: false
    description: >
      The fields to be included in the response.
      Cannot coexist with `extraFields`.
      E.g. `"firstName,lastName,dateBlocked"`
    collectionFormat: multi
    default: null
  extraFields:
    name: extraFields
    in: query
    type: string
    required: false
    description: >
      The fields to be included in the response in addition to all the default fields.
      To select from default fields, use `fields`.
      Cannot coexist with `fields`.
      E.g. `"firstName,lastName,dateBlocked"`
    collectionFormat: multi
    default: null
tags:
  - name: Account
    description: |
      An account is the lowest-level structure in your programs used to organize participants.

      Key aspects of an account:

       - Each account can only be referred once.
       - Classic only The account status (TRIAL, PAID, CANCELLED) is set at the account level.
       - Rewards are also earned at the account level

      For information about how to structure your user and account ids read the [Shared vs Solo Accounts article](/shared-vs-solo-accounts/) .

  - name: User
    description: |
      Users are the people in your program. In other places a User might also be called a Contact, Lead or Participant. Users are each mapped to one specific account.

      The following information is controlled at the user level:

       - First and last name
       - Email address
       - Referral code
       - Share links

      For information about how to structure your user and account ids read the [Shared vs Solo Accounts article](/shared-vs-solo-accounts/) .
  - name: Share Links
    description: |
      Share links are made available to a Referrer to provide to their friends and family to click and be directed to your referral program landing page.

      The sharelinks are segmented by Engagement Medium, which is the channel the Referrer accessed the program to be able to share out their referral through. For each Engagment Medium, like `EMBED`, a link is provided for each available Share Medium. This segmentation is used to power the [SaaSquatch analytics platform](/features/analytics/) to provide information about how, and where, your users are interacting with your referral program.
      For example, The `WHATSAPP` link from the `MOBILE` section is intended to be used to indicated to our system that the Referrer accessed the referral program from a mobile device and shared their referral with their friend using Whatsapp. More information about available [Engagement Mediums](/success/touchpoints/) and [Share Mediums](/success/share-options/) can be found in our success center.

      Share links work by dropping a tracking cookie in the user's browser when the user clicks the link and is directed to your referral program's landing page. This cookie includes the referral code of the Referrer that shared it. Once on your website this cookie can be read using the squatch.js [autofill](/developer/squatchjs/v2/#3-autofill-the-referral-code) method and is also automatically picked up by our squatch.js library to connect referrals.

      The referral code is also passed along to your referral program landing page as the URL parameter `rsCode`. For example `http://ssqt.co/pZVp` redirects to `https://www.google.ca/?rsCode=JOHNDOE`.
  - name: User Event
    description: |
      Any time a user interacts with your system, you would send SaaSquatch an event with details about this interaction.

      Some examples of User Events to send to SaaSquatch include:

      - Purchases or Transactions
      - Subscription Creation/Update/Removal
      - Mailing List Subscription

      With each of these (and any other events you pass over), the more information you provide with the User Event, the more granual control is available in the SaaSquatch system when processing these events.

      These events are then leveraged to update user information and trigger actions within your running Growth Automation programs.
  - name: Referral Code
    description: |
      When a user is registered in our system they are provided a unique referral code. This code typically comes in the form of FIRSTNAMELASTNAME, such as JOHNDOE. By default the referral code is shown in the referral widget right underneath the main text.

      The referral code provides a simple method for users to connect with your referral program. They are relatively short human-readable codes which users can share with their friends and family. Many people are familiar with the concept of a coupon code so using the referral codes as part of your referral program can make the process easier to understand.

      A user will be provided one referral code for every referral program or partner program that you are running in your tenant.
  - name: Referral
    description: A Referral tracks who has referred whom.
  - name: Reward Balance
    description: Reward Balances summarizes the Rewards in someone's account.
  - name: Reward
    description: |
      A Reward keeps track of a prize, discount or credit that someone has received.

      All reward types other than gift card integrated rewards can be cancelled using the SaaSquatch API, or through the SaaSquatch Admin portal, if they have not already been redeemed.
  - name: Webhook
    description: |
      Webhooks can be used to do real time actions and data synchronization from SaaSquatch.

      Webhooks let you register a URL that we will POST to anytime an event happens in your account. When the event occurs, for example when a vanity coupon code is created for a new user, SaaSquatch creates an event object. This object contains all the relevant information, including the type of event and the data associated with that event. SaaSquatch then sends an HTTP POST request with the event object to any URLs in your account's webhook settings. You can find a full list of all event types below.
  - name: Export
    description: Exports are used to do bulk data dumps from your SaaSquatch account.
  - name: Theme
    description: Themes control the look and feel of your program's widgets.

  - name: Discount
    description: Endpoints for working with discounts. **Most of these are deprecated** in favor of using Reward endpoints.
    x-deprecated: true

  - name: Deprecated
    description: Endpoints that have been deprecated.
    x-meta: true
  - name: Open Endpoint
    description: Open Endpoints are special methods designed specifically for Client-facing applications like the Mobile SDK and Javascript SDK.
    x-meta: true
  - name: Classic Only
    description: An endpoint or attribute that only works with the Classic referral programs, and no other programs.
    x-meta: true
  - name: Modern Only
    description: An endpoint or attribute that does not work with the Classic referral program.
    x-meta: true
paths:
  "/{tenant_alias}/accountsync":
    post:
      deprecated: true
      summary: Create or Update an account
      operationId: upsertAccount
      x-docs-anchor: account_sync
      tags:
        - Account
        - Classic Only
        - Deprecated
      security:
        - APIKey: []
      description: |
        Use this method to update SaaSquatch when the status of an account changes or when a new account is created.

        This call is only available on an API-only program. Making this call on a payment provider program will fail and return a 403 error indicating the call is incompatible with your type of program.
      parameters:
        - name: account
          in: body
          description: Account details of the account to be created or updated
          schema:
            $ref: "#/definitions/Account"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Account created or updated
          examples:
            "application/json":
              id: a1234
              currency: USD
              subscription:
                status: PAID
                value: 1
                billingIntervalType: DAY
                billingIntervalValue: 1
              referral:
                code: 3j033r
          schema:
            $ref: "#/definitions/Account"
        403:
          description: Account sync failed
          examples:
            "application/json":
              message: "Account sync failed. This push is not valid for your tenant type[STRIPE]"
              statusCode: 403
              apiErrorCode: "API_REQUEST_NOT_SUPPORTED"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/account/{accountId}":
    get:
      summary: Lookup an account
      operationId: getAccount
      x-docs-anchor: get_account
      tags:
        - Account
        - Classic Only
      security:
        - APIKey: []

      description: |
        Looks up an Account based upon `id` and returns the stored account information.
        This method just returns the details of the account in question, and not all associated properties like Rewards, ShareLinks, Balances or Referrals.

        This call is only available on an API-only program. Making this call on a payment provider program will fail and return a 403 error indicating the call is incompatible with your type of program.
      parameters:
        - name: accountId
          in: path
          description: "The `id` of the Account to look up."
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Account found
          examples:
            "application/json":
              id: "89842"
              subscription:
                status: "PAID"
                value: 29.99
                billingIntervalType: "MONTH"
                billingIntervalValue: 1
              referral:
                code: "WILLSANDERSON2"
              currency: "USD"
          schema:
            $ref: "#/definitions/Account"
        403:
          description: Account sync failed
          examples:
            "application/json":
              message: "Account sync failed. This push is not valid for your tenant type[STRIPE]"
              statusCode: 403
              apiErrorCode: "API_REQUEST_NOT_SUPPORTED"
        404:
          description: Account NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/user":
    post:
      summary: Create or Update a User
      operationId: createUser
      x-docs-anchor: create_user
      tags:
        - User
        - Classic Only
      security:
        - APIKey: []
      description: |
        This method creates or updates a User object by performing an atomic upsert operation. Using this method will either replace the information stored about a given user, or
        create a new user if no User with a matching `id` is found. This method is helpful for synchronizing user information from your database into Referral SaaSquatch.
        This method will not create or update the Account linked by `accountId`. When creating users for the first time ensure that the Account already exists or create it before using this call.
        See the article on [Shared vs Solo Accounts](/shared-vs-solo-accounts/) for more information on Users and Accounts and how they relate.
      parameters:
        - name: user
          in: body
          description: Details of the User to be created or updated
          required: true
          schema:
            $ref: "#/definitions/UserStub"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: User Created or Updated
          examples:
            "application/json":
              $ref: "#/definitions/User/example"
          schema:
            $ref: "#/definitions/User"
        default:
          $ref: "#/responses/GeneralError"
    get:
      summary: Lookup a user by Referral Code
      operationId: findUserByReferralCode
      x-docs-anchor: get_user_by_referralcode
      tags:
        - User
        - Classic Only
      security:
        - APIKey: []

      description: |
        Looks up a user based upon their `referralCode` and returns their personal information.
        This method is useful for retrieving the user when only the Referral Code is available.
        For example when a referred user enters a Referral Code during checkout and you want to find out who this Referral Code belongs to.
        `referralCode` and `shareLinks` in the response are for the classic referral program.
      parameters:
        - name: referralCode
          in: query
          description: "The `referralCode` of the user you want to retrieve. For example BOBTESTERSON."
          required: true
          type: string
          x-example: "BOBTESTERSON"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: User found
          examples:
            "application/json":
              $ref: "#/definitions/User/example"
          schema:
            $ref: "#/definitions/User"
        404:
          description: User NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/account/{accountId}/user/{userId}":
    get:
      summary: Lookup a user
      operationId: getUser
      x-docs-anchor: get_user
      tags:
        - User
        - Classic Only
      security:
        - APIKey: []
      description: |
        Looks up a user based upon their `id` and returns their personal information.
        This method just returns the details of the user in question, and not all associated properties like Rewards, Balances, or Referrals.
      parameters:
        - name: accountId
          in: path
          description: "The `id` of the Account that this user is a member of. See [Shared vs. Solo accounts](/shared-vs-solo-accounts/) for more info."
          required: true
          type: string
        - name: userId
          in: path
          description: "The `id` of the User to find"
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: User found
          examples:
            "application/json":
              $ref: "#/definitions/User/example"
          schema:
            $ref: "#/definitions/User"
        404:
          description: User NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/account/{accountId}/user/{userId}/pii":
    get:
      summary: Lookup a user PII
      operationId: getUserPII
      x-docs-anchor: get_user_pii
      tags:
        - User
      security:
        - APIKey: []
      description: |
        Returns details of the Personally identifiable information stored in the SaaSquatch system for a specific SaaSquatch user.

        > **Warning!** This method should only be used in connection with data protection and privacy compliance.
        >
        > For programatically looking up information about users within your SaaSquatch project, please use the [Lookup User endpoint](#open_get_user)
      parameters:
        - name: accountId
          in: path
          description: "The `id` of the Account to lookup"
          required: true
          type: string
        - name: userId
          in: path
          description: "The `id` of the User to lookup"
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: User found
          examples:
            "application/json":
              $ref: "#/definitions/UserPII/example"
          schema:
            $ref: "#/definitions/UserPII"
        404:
          description: User NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/open/account/{accountId}/user/{userId}/events":
    post:
      summary: Track User Event
      operationId: trackEvent
      x-docs-anchor: trackEvent
      tags:
        - User Event
        - Open Endpoint
        - Modern Only
      security:
        - APIKey: []
        - UserJWT: []

      description: |
        This method can be used to track when users <a href="/developer/purchase-object/">make purchases</a>, download items, or take other meaningful actions that you want to use to trigger your programs.

        To prevent processing an event more than once, you can provide an idempotency
        key to achieve "at most once" processing semantics. The idempotency key
        uniquely identifies the event, and is generated by the caller.

        The idempotency key can be any string identifier that your system associates
        with the event, with the following restrictions:

        - It must be at least 8 characters long
        - It must be no more than 64 characters long
        - It can only contain alphanumerics characters, as well as the `.`, `-`,
          or `_` characters

        For example, a good choice for an idempotency key is a UUID, in particular
        a random version 4 UUID like `ec524601-975c-458a-9948-ae4448ce8944`.

        Idempotency keys are guaranteed to be stored by SaaSquatch for at least 24 hours,
        such that any event inputs with the same idempotency key within 24 hours will
        be guaranteed to process the events only once.

        Subsequent attempts to process an event with an idempotency key that has already
        been processed once will result in an HTTP 409 Conflict response, so you will
        need to ensure that you are handling this status code in your request logic.

      parameters:
        - name: accountId
          in: path
          description: "The `id` of the Account associated with the User being tracked. See [Shared vs. Solo accounts](/shared-vs-solo-accounts/) for more info."
          required: true
          type: string
        - name: userId
          in: path
          description: "The `id` of the User being tracked"
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
        - name: body
          in: body
          description: Details of the events to be tracked
          required: true
          schema:
            type: object
            required:
              - userId
              - accountId
              - events
            properties:
              userId:
                description: "The `id` of the User being tracked"
                type: string
                example: "someUserId"
              accountId:
                description: "The `id` of the Account associated with the User being tracked. See [Shared vs. Solo accounts](/shared-vs-solo-accounts/) for more info."
                type: string
                example: "someAccountId"
              idempotencyKey:
                description: The idempotency key for the logged events
                type: string
                example: "ec524601-975c-458a-9948-ae4448ce8944"
              events:
                description: An array of events
                type: array
                items:
                  type: object
                  description: Event Payload
                  required:
                    - key
                  properties:
                    key:
                      description: The unique name of the event
                      type: string
                      example: "purchase"
                    fields:
                      description: |
                        Additional fields about the event.
                        Strings longer than 1500 UTF-8 bytes are not supported.
                        Arrays of arrays are not supported.
                      type: object
                      additionalProperties: true
                      example: { currency: CAD }
                    dateTriggered:
                      description: The date the event was triggered
                      type: number

      responses:
        200:
          description: Event tracked
          examples:
            "application/json":
              userId: "someUserId"
              accountId: "someAccountId"
              events:
                - id: "5bb3978dbd8bfe821a5f26f3"
                  key: "purchase"
                  fields:
                    currency: "CAD"
                  dateTriggered: 1538496397475
                  dateReceived: 1538496397475
                  dateProcessed: 1538496397479
          schema: {}
        404:
          description: User/Account NOT found
          schema:
            $ref: "#/definitions/Error"
        409:
          description: Idempotency key conflict
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/account/{accountId}/user/{userId}/sharelinks":
    get:
      deprecated: true
      summary: Lookup a user's share links
      operationId: getSharelinks
      x-docs-anchor: get_sharelinks
      tags:
        - Share Links
        - Classic Only
        - Deprecated
      security:
        - APIKey: []

      description: |
        Gets the share links for a user. Share links are the links that people use to refer their friends and are the same links used in the Referral SaaSquatch widgets. The main
        use case for this method is to look up share links to include in other channels like email marketing, CRM and product integration when a widget or mobile webview can't be
        easily used. For example, one could write "Share this link with your friends, and get rewarded when they sign up" and include the share link looked up using this method.

        All share links work by dropping a tracking cookie when someone clicks the link and redirecting the new user to a landing page. This cookie includes the value of the
        referral code of the person that shared it. The cookie
        can be read using the `autofill` function of Squatch.js and is also passed along as the `rsCode` parameter in the redirect.
        For example `http://ssqt.co/pZVp` redirects to `https://www.google.ca/?rsCode=THIRDUSER`.

        There are many share links for each user, each one tagged with additional metadata for tracking the effectiveness of sharing channels. For example the `facebookShareLink` is used in the
        share on Facebook functionality of the widget. When people share on facebook using the widget that `facebookShareLink` will be posted on their wall so that when new people click on that
        link they will be tracked as a referral and attributed back to Facebook. Note that this does not necessarily guarantee tracking; the generic `shareLink` could simply be copied
        and pasted on to Facebook, and due to limitation on http referer information passed on by browsers, it may not be possible to determine which share medium a new sign up came from.

        In some cases it is preferable to have users share their referral code with friends instead of sharing their referral link. For example mobile apps and cookie blocking may prevent
        a share link from successfully tracking a referral, and having an input box for "Referral Code" on your product sign up form gets around these limitations and will ensure that more
        types of referrals can be tracked. Use the [Lookup a user API call](#get_user) to find a user's referral code.
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: accountId
          in: path
          description: The ID of the account to look up
          required: true
          type: string
        - name: userId
          in: path
          description: Filters share links by `user.id`.
          required: true
          type: string
      responses:
        200:
          description: A list of share links
          schema:
            $ref: "#/definitions/Sharelink"
          examples:
            "application/json":
              $ref: "#/definitions/Sharelink/example"
        404:
          description: User/Account not found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/account/{accountId}/user/{userId}/shareurls":
    get:
      summary: Lookup a user's share URLs
      operationId: getShareURLs
      x-docs-anchor: get_shareurls
      tags:
        - Share Links
      security:
        - APIKey: []

      description: |
        This API method returns the full list of referral share links for a user. Optional filter parameters are available to return only links of a specific share or engagement medium.

        Share links are made available to a Referrer to provide to their friends and family to click and be directed to your referral program landing page.

        The sharelinks are segmented by Engagement Medium, which is the channel the Referrer accessed the program to be able to share out their referral through. For each Engagment Medium, like `EMBED`, a link is provided for each available Share Medium. This segmentation is used to power the [SaaSquatch analytics platform](/features/analytics/) to provide information about how, and where, your users are interacting with your referral program.
        For example, The `WHATSAPP` link from the `MOBILE` section is intended to be used to indicated to our system that the Referrer accessed the referral program from a mobile device and shared their referral with their friend using Whatsapp. More information about available [Engagement Mediums](/success/touchpoints/) and [Share Mediums](/success/share-options/) can be found in our success center.

        Additionally, a clean share link is provided. If the given link is a vanity link, then the clean share link will have no encoding, for example `http://example.com/free`. The clean share link will have the `UNKNOWN` Share Medium and `UNKNOWN` Engagement Medium link.

        Share links work by dropping a tracking cookie in the user's browser when the user clicks the link and is directed to your referral program's landing page. This cookie includes the referral code of the Referrer that shared it. Once on your website this cookie can be read using the squatch.js [autofill](/developer/squatchjs/v2/#3-autofill-the-referral-code) method and is also automatically picked up by our squatch.js library to connect referrals.

        The referral code is also passed along to your referral program landing page as the URL parameter `rsCode`. For example `http://ssqt.co/pZVp` redirects to `https://www.google.ca/?rsCode=JOHNDOE`.
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: accountId
          in: path
          description: The ID of the account to look up
          required: true
          type: string
        - name: userId
          in: path
          description: Filters share urls by `user.id`.
          required: true
          type: string
        - name: engagementMedium
          in: query
          description: Filters share urls by `engagementMedium`.
          required: false
          type: string
        - name: shareMedium
          in: query
          description: Filters share urls by `shareMedium`.
          required: false
          type: string
        - name: programId
          in: query
          description: The ID of the program
          required: false
          type: string
      responses:
        200:
          description: A list of share urls
          schema:
            $ref: "#/definitions/Shareurls"
          examples:
            "application/json":
              $ref: "#/definitions/Shareurls/example"
        404:
          description: User/Account not found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/account/{accountId}/user/{userId}/block":
    post:
      summary: Block user
      operationId: blockUser
      x-docs-anchor: block_user
      tags:
        - User
      security:
        - APIKey: []

      description: |
        Block a user from making successful referrals based upon their user and account `id`.
        More information about blocking users from participating in your referral program can be [found in the SaaSquatch docs](/developer/referral-security/#user-blocking).
      parameters:
        - name: accountId
          in: path
          description: "The `id` of the Account associated with the User being blocked. See [Shared vs. Solo accounts](/shared-vs-solo-accounts/) for more info."
          required: true
          type: string
        - name: userId
          in: path
          description: "The `id` of the User to block"
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: User blocked successfully
          examples:
            "application/json": {}
          schema: {}
        403:
          description: User already blocked
          schema:
            $ref: "#/definitions/Error"
        404:
          description: User/Account NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/account/{accountId}/user/{userId}/unblock":
    post:
      summary: Unblock user
      operationId: unblockUser
      x-docs-anchor: unblock_user
      tags:
        - User
      security:
        - APIKey: []

      description: |
        Unblock a user based upon their user and account `id`.
        More information about blocking users from participating in your referral program can be [found in the SaaSquatch docs](/developer/referral-security/#user-blocking).
      parameters:
        - name: accountId
          in: path
          description: "The `id` of the Account associated with the User being unblocked. See [Shared vs. Solo accounts](/shared-vs-solo-accounts/) for more info."
          required: true
          type: string
        - name: userId
          in: path
          description: "The `id` of the User to unblock"
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: User unblocked successfully
          examples:
            "application/json": {}
          schema: {}
        403:
          description: User not blocked
          schema:
            $ref: "#/definitions/Error"
        404:
          description: User/Account NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/users":
    get:
      summary: List users
      operationId: listUsers
      x-docs-anchor: list_users
      tags:
        - User
      security:
        - APIKey: []
      description: |
        List all of the Users in your Referral SaaSquatch tenant. This method is the primary way of getting a full list of everyone that has been identified through the API, Squatch.js or mobile widgets.
        This method supports pagination using the parameters for `limit` and `offset` to iterate through a very large list of records.
        You can also search for particular users using the `query` method. To find information about which users have completed referrals, use the [List referrals](#list_referrals) method.
      parameters:
        - name: query
          in: query
          description: "A search query that can be used to filter users by email, name or ID."
          type: string
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Users found
          examples:
            "application/json":
              count: 1
              totalCount: 1
              users:
                - id: "14125"
                  accountId: "89842"
                  email: "mark@example.com"
                  firstName: "Mark"
                  lastName: "Testerson"
                  referralCode: "MARKTESTER"
                  imageUrl: ""
                  dateCreated: 1414452680584
                  emailHash: "a65a76ba72e5a0b1e6253efce357abb6"
          schema:
            $ref: "#/definitions/UserList"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/code/{code}":
    get:
      deprecated: true
      summary: Lookup a referral code
      operationId: getCode
      x-docs-anchor: get_code
      tags:
        - Referral Code
        - Deprecated
      security:
        - APIKey: []

      description: |
        Looks up a referral code and the attached details. Deprecated in favour of its Open Endpoint equivalent.
      parameters:
        - name: code
          in: path
          description: The referral code to look up, E.g. "BOBTESTERSON". This can be a user's primary or non primary referral code.
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Referral code found
          examples:
            "application/json":
              code: "BOBTESTERSON"
              dateCreated: 1411600868797
              programId: "referral-a"
              referrerName: "Bob T"
              reward:
                $ref: "#/definitions/RewardTemplate/example/CREDIT"
              # - code: "BOBTESTERSON"
              #   dateCreated: 1411600868797
              #   referrerName: "Bob T"
              #   programId: "referral-b"
              #   reward:
              #     $ref: "#/definitions/RewardTemplate/example/PCT_DISCOUNT"
          schema:
            $ref: "#/definitions/Code"
        404:
          description: Referral code NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/referrals":
    get:
      summary: List referrals
      operationId: listReferrals
      x-docs-anchor: list_referrals
      tags:
        - Referral
      security:
        - APIKey: []

      description: |
        List all of the referrals in your Referral SaaSquatch tenant. This method is the primary way of getting a full list of everyone that has made a referral and everyone that has been referred,
        and supports pagination using the parameters for `limit` and `offset` to iterate through a very large list of records.
        You can also use the query parameters for `referringAccountId` and `referringUserId` to filters this list of referrals to only include those made by a given user.
      parameters:
        - name: referringAccountId
          in: query
          type: string
          description: "When included, filters the results to only referrals that were referred users with this `AccountId`"
        - name: referringUserId
          in: query
          type: string
          description: "When included, filters the results to only referrals that were referred users with this `UserId`"
        - name: dateReferralPaid
          in: query
          type: string
          description: "When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that converted between 0 and 123412451."
        - name: dateReferralEnded
          in: query
          type: string
          description: "When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that ended between 0 and 123412451."
        - name: referredModerationStatus
          in: query
          type: string
          description: "When included, filters the result to only include referred users with that status. Statuses that are accepted: `PENDING`, `APPROVED` or `DENIED`."
        - name: referrerModerationStatus
          in: query
          type: string
          description: "When included, filters the result to only include referrers with that status. Statuses that are accepted: `PENDING`, `APPROVED` or `DENIED`."
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: A list of referrals
          schema:
            $ref: "#/definitions/ReferralList"
          examples:
            "application/json":
              count: 2
              totalCount: 4
              referrals:
                - id: "5462600de4b09b1c41108f28"
                  referredUser:
                    $ref: "#/definitions/User/example"
                  referrerUser:
                    $ref: "#/definitions/User/example"
                  referredReward:
                    $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
                  referrerReward: null
                  referralCodeUsed: "LORETTABURKE10"
                  shareLinkUsed: "http://ssqt.co/mPbcF5"
                  moderationStatus: "ACTIONED"
                  dateReferralStarted: 1415733261238
                  dateReferralPaid: null
                  dateReferralEnded: null
                  dateModerated: 1427410131006
                  referredModerationStatus: "APPROVED"
                  referrerModerationStatus: "APPROVED"
                - id: "546270a6e4b0c1871186a920"
                  referredUser:
                    $ref: "#/definitions/User/example"
                  referrerUser:
                    $ref: "#/definitions/User/example"
                  referredReward:
                    $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
                  referrerReward:
                    $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
                  referralCodeUsed: "FREE"
                  sharelinkUsed: "http://example.com/free?mn"
                  moderationStatus: "ACTIONED"
                  dateReferralStarted: 1415737510411
                  dateReferralPaid: 1415737557217
                  dateReferralEnded: null
                  dateModerated: 1427410131029
                  referredModerationStatus: "APPROVED"
                  referrerModerationStatus: "APPROVED"
                  fraudSignals:
                    ip:
                      message: "Referrer and referred came from the same IP"
                      score: 50
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/referrals/{referralId}":
    get:
      summary: Lookup a Referral
      operationId: getReferral
      x-docs-anchor: get_referral
      tags:
        - Referral
      security:
        - APIKey: []

      description: |
        Looks up a single Referral object by it's associated `id`. This method is helpful for looking into a particular referral of interest. Since it requires the `id` of the referral to
        be specified, it isn't applicable for querying all referrals to find those made by a particular user or account. To query for those referrals use the [list referrals](#list_referrals) endpoint instead
        with query parameters specified.
      parameters:
        - name: referralId
          in: path
          type: string
          description: "The `id` of the referral to look up"
          required: true
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Referral found
          schema:
            $ref: "#/definitions/Referral"
          examples:
            "application/json":
              $ref: "#/definitions/Referral/example"
            # "application/json":
            #   id: "546270a6e4b0c1871186a920"
            #   referredUser:
            #     $ref: "#/definitions/User/example"
            #   referrerUser:
            #     $ref: "#/definitions/User/example"
            #   referredReward:
            #     $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
            #   referrerReward:
            #     $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
            #   moderationStatus: "ACTIONED"
            #   dateReferralStarted: 1415737510411
            #   dateReferralPaid: 1415737557217
            #   dateReferralEnded: null
            #   dateModerated: 1427410131029
            #   referredModerationStatus: "APPROVED"
            #   referrerModerationStatus: "APPROVED"
            #   fraudSignals: null
        404:
          description: Referral NOT found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/referrals/moderate":
    post:
      summary: Moderate referrals
      operationId: moderateReferrals
      x-docs-anchor: moderate_referrals
      tags:
        - Referral
        - Classic Only
      security:
        - APIKey: []

      description: |
        Moderates one or several referrals by either approving or denying.
        Moderation can apply to one side of a referral, the other side, or both sides (Referrer and Referred).
        When a referral is denied, the associated reward will be "cancelled".
        A referral can be moderated several times, subsequently cancelling and un-cancelling the associated reward or rewards, and can be done as long as the associated reward is `cancellable`.
        Some rewards such as the coupons automatically generated by Referral SaaSquatch into Stripe and Recurly are not `cancellable` and requests to change the moderation will error.
      parameters:
        - name: moderationBulkRequest
          in: body
          description: Details of the referrals to be moderated
          schema:
            $ref: "#/definitions/ReferralModerationBulkRequest"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Success
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

  "/{tenant_alias}/reward/balance":
    get:
      summary: List reward balances
      operationId: listRewardBalances
      x-docs-anchor: list_balances
      tags:
        - Reward Balance
      security:
        - APIKey: []

      description: |
        Looks up the balance for all rewards of the same type and units.
      parameters:
        - name: accountId
          in: query
          description: The ID of the account to look up
          required: true
          type: string
        - name: userId
          in: query
          description: Filters rewards by `user.id`.
          type: string
        - name: rewardTypeFilter
          in: query
          description: Filters rewards by `type`.
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: A list of reward balances
          schema:
            $ref: "#/definitions/RewardBalanceList"
          examples:
            "application/json":
              - $ref: "#/definitions/RewardBalance/example/CREDIT"
              - $ref: "#/definitions/RewardBalance/example/PCT_DISCOUNT"
              - $ref: "#/definitions/RewardBalance/example/FUELTANK"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/credit/bulkredeem":
    post:
      summary: Debit a reward balance
      operationId: debitRewardBalance
      x-docs-anchor: debit_balance
      tags:
        - Reward Balance
      security:
        - APIKey: []

      description: "Used to redeem the credit earned from a referral program. Permanently debits an account balance. Works with: `CREDIT`"
      parameters:
        - name: debit
          in: body
          description: Details of the debit
          required: true
          schema:
            $ref: "#/definitions/RewardBalanceDebitRequest"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Balance debitted
          examples:
            "application/json":
              creditRedeemed: 200
              creditAvailable: 0
              unit: "cents"
          schema:
            $ref: "#/definitions/RewardDebitResponse"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/reward":
    get:
      summary: List an account's rewards
      operationId: getRewards
      x-docs-anchor: list_rewards
      tags:
        - Reward
      security:
        - APIKey: []

      description: |
        Looks up a list of single rewards
      parameters:
        - name: accountId
          in: query
          description: The ID of the account to look up
          required: true
          type: string
        - name: userId
          in: query
          description: Filters rewards by `user.id`.
          type: string
        - name: rewardTypeFilter
          in: query
          description: Filters rewards by `type`.
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: A list of rewards
          schema:
            $ref: "#/definitions/RewardList"
          examples:
            "application/json":
              - $ref: "#/definitions/Reward/example/CREDIT"
              - $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
              - $ref: "#/definitions/Reward/example/FUELTANK"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/reward/{id}":
    get:
      summary: Lookup a single reward
      operationId: lookupReward
      x-docs-anchor: lookup_reward
      tags:
        - Reward
      security:
        - APIKey: []
      description: "Used to lookup an individual reward using the ID of the reward. Works with: `CREDIT`, `PCT_DISCOUNT`, and `FUELTANK`"
      parameters:
        - name: id
          in: path
          description: The ID of the specific reward to lookup
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        201:
          description: Reward information
          schema:
            $ref: "#/definitions/Reward"
          examples:
            "application/json":
              $ref: "#/definitions/Reward/example/CREDIT"
            # - $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
            # - $ref: "#/definitions/Reward/example/FUELTANK"

        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/credit/{id}/redeem":
    post:
      summary: Redeem a single reward
      operationId: debitReward
      x-docs-anchor: debit_reward
      tags:
        - Reward
      security:
        - APIKey: []
      description: "Used to redeem an individual credit earned from a referral program. Works with: `CREDIT`"
      parameters:
        - name: id
          in: path
          description: The ID of the specific reward to be redeemed
          required: true
          type: string
        - name: debit
          in: body
          description: Details of the debit
          schema:
            $ref: "#/definitions/RewardDebitRequest"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Reward debitted
          examples:
            "application/json":
              creditRedeemed: 200
              creditAvailable: 1800
              unit: "cents"
          schema:
            $ref: "#/definitions/RewardDebitResponse"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/reward/{id}/cancel":
    post:
      summary: Cancel a single reward
      operationId: cancelReward
      x-docs-anchor: cancel_reward
      tags:
        - Reward
      security:
        - APIKey: []
      description: "Used to cancel an individual reward earned from a referral program. Works with: `CREDIT`, `PCT_DISCOUNT`, and `FUELTANK`"
      parameters:
        - name: id
          in: path
          description: The ID of the specific reward to be cancelled
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Reward cancelled
          examples:
            "application/json":
              $ref: "#/definitions/Reward/example/CREDIT"
          schema:
            $ref: "#/definitions/Reward"
        400:
          description: Reward is not cancellable
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Reward does not exist
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/rewards/account/{accountId}/user/{userId}":
    post:
      summary: Create a single reward
      operationId: createReward
      x-docs-anchor: create_reward
      tags:
        - Reward
      security:
        - APIKey: []

      description: |
        Used to create a reward for a specified user. Note that the reward will only be redeemed automatically
        if the default program supports automatic redemption for the provided reward type (see the [install guides](/guides/)
        for more on automatic redemption).
      parameters:
        - name: userId
          in: path
          description: The ID of the user that will be given the reward
          required: true
          type: string
        - name: accountId
          in: path
          description: The ID of the account that will be given the reward
          required: true
          type: string
        - name: reward
          in: body
          description: Details of the reward to create
          schema:
            $ref: "#/definitions/NewReward"
        - $ref: "#/parameters/tenant_alias"
      responses:
        201:
          description: Reward created
          schema:
            $ref: "#/definitions/Reward"
          examples:
            "application/json":
              - $ref: "#/definitions/Reward/example/CREDIT"
              - $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
              - $ref: "#/definitions/Reward/example/FUELTANK"

        default:
          $ref: "#/responses/GeneralError"

  ## Open API Endpoints
  "/{tenant_alias}/open/account/{accountId}/user/{userId}":
    put:
      summary: User Upsert
      operationId: openUserUpsert
      x-docs-anchor: open_user_upsert
      tags:
        - User
        - Open Endpoint
      security:
        - APIKey: []
        - UserJWT: []
      description: |
        This method updates/creates a user and an account and returns the user object representing that newly created user/account.

        You can provide vanity referral codes and sharelinks in a user upsert. Make sure to check the tenant setting `allowReferralCodeEditOnUserUpsert`, if it is set to `FALSE` then referral codes added when upserting an existing user will be ignored. New sharelinks and referral codes will be set as primary for the upserted user. If a referral code is passed without an associated sharelink for that program, then one will be generated and vice versa for sharelinks.

        Because this call creates a user, it requires either a [write token](../openendpoints/) or an API key.

      parameters:
        - name: accountId
          in: path
          description: The account to upsert
          required: true
          type: string
        - name: userId
          in: path
          required: true
          description: The user to upsert
          type: string
        - name: user
          in: body
          schema:
            $ref: "#/definitions/OpenUserStub"
        - $ref: "#/parameters/tenant_alias"
        - $ref: "#/parameters/fields"
        - $ref: "#/parameters/extraFields"
      responses:
        200:
          description: Information about the upserted user
          examples:
            "application/json":
              $ref: "#/definitions/OpenUser/example"
          schema:
            $ref: "#/definitions/OpenUser"
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"

    post:
      summary: Create a user and account
      operationId: openCreateUser
      x-docs-anchor: open_create_user
      tags:
        - User
        - Open Endpoint
      security:
        - APIKey: []
        - UserJWT: []
      description: |
        This method creates a user and an account and returns the user object representing that newly created user/account.

        You can provide vanity referral codes and sharelinks when creating a user and account. Make sure to check the tenant setting `allowReferralCodeEditOnUserUpsert`, if it is set to `FALSE` then referral codes added when using this method on an existing user will be ignored. New sharelinks and referral codes will be set as primary for the given user. If a referral code is passed without an associated sharelink for that program, then one will be generated and vice versa for sharelinks.

        Because this call creates a user, it requires either a [write token](../openendpoints/) or an API key.
      parameters:
        - name: accountId
          in: path
          description: The account to create
          required: true
          type: string
        - name: userId
          in: path
          required: true
          description: The user to create
          type: string
        - name: user
          in: body
          schema:
            $ref: "#/definitions/OpenUserStub"
        - $ref: "#/parameters/tenant_alias"
        - $ref: "#/parameters/fields"
        - $ref: "#/parameters/extraFields"
      responses:
        201:
          description: Information about the newly created user
          examples:
            "application/json":
              $ref: "#/definitions/OpenUser/example"
          schema:
            $ref: "#/definitions/OpenUser"
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
    get:
      summary: Lookup a user
      operationId: openGetUser
      x-docs-anchor: open_get_user
      tags:
        - User
        - Open Endpoint
      security:
        - APIKey: []
        - UserJWT: []
      description: |
        Looks up a user based upon their `id` and returns their personal information including sharelinks. This endpoint requires a [read token](../openendpoints/) or an API key.

        This is an [Open Endpoint](../openendpoints/) and disabled by default. Contact support to enable the open endpoints.
      parameters:
        - name: accountId
          in: path
          description: A valid Account ID that a user is associated with
          required: true
          type: string
        - name: userId
          in: path
          description: A valid User ID
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
        - $ref: "#/parameters/fields"
        - $ref: "#/parameters/extraFields"
      responses:
        200:
          description: User found
          examples:
            "application/json":
              $ref: "#/definitions/OpenUser/example"
          schema:
            $ref: "#/definitions/OpenUser"
        401:
          description: Unauthorized
          schema:
            $ref: "#/definitions/Error"
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Account not found
          schema:
            $ref: "#/definitions/Error"

    delete:
      summary: Delete a user
      operationId: openDeleteUser
      x-docs-anchor: open_delete_user
      tags:
        - User
        - Open Endpoint
      security:
        - APIKey: []
      description: |
        Delete a user in your SaaSquatch project. By default this endpoint only deletes a User on an Account (and not the Account itself). Learn more about Accounts vs. Users in our article on [Account Structure](/shared-vs-solo-accounts/).

        To delete both the Account (and all the users on the account), use the [Delete Account endpoint](#open_delete_account).

        Learn more about deleting participants within your SaaSquatch project in our article on [Participant Deletion](/features/participant-deletion)

        Include the `doNotTrack` query parameter as `true` to indicate to SaaSquatch that the user should not be able to be re-registered on the same account. Learn more about `doNotTrack` in our article on [Participant Deletion](/features/participant-deletion)

        Include the `preserveEmptyAccount` query parameter as `false` to indicate to SaaSquatch that the users account should be deleted if there are no other users in the account.
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: accountId
          in: path
          description: The ID of the account to be deleted
          required: true
          type: string
        - name: userId
          in: path
          description: The ID of the user to be deleted
          required: true
          type: string
        - name: doNotTrack
          in: query
          description: Do not track this user (this user cannot be re-registered in SaaSquatch on the same account), false by default. Learn more about `doNotTrack` in our article on [Participant Deletion](/features/participant-deletion)
          type: boolean
        - name: preserveEmptyAccount
          in: query
          description: Do not delete accounts when all the users in the account are deleted, true by default
          type: boolean

      responses:
        204:
          description: User successfully deleted
        404:
          description: No user found for the provided id
          schema:
            $ref: "#/definitions/Error"

  "/{tenant_alias}/open/account/{accountId}/user/{userId}/shareurls":
    get:
      summary: Lookup a user's share URLs
      operationId: openGetShareURLs
      x-docs-anchor: open_get_shareurls
      tags:
        - Share Links
        - Open Endpoint
      security:
        - APIKey: []
        - UserJWT: []
      description: |
        This API method returns the full list of referral share links for a user. Optional filter parameters are available to return only links of a specific share or engagement medium.

        Share links are made available to a Referrer to provide to their friends and family to click and be directed to your referral program landing page.

        The sharelinks are segmented by Engagement Medium, which is the channel the Referrer accessed the program to be able to share out their referral through. For each Engagment Medium, like `EMBED`, a link is provided for each available Share Medium. This segmentation is used to power the [SaaSquatch analytics platform](/features/analytics/) to provide information about how, and where, your users are interacting with your referral program.
        For example, The `WHATSAPP` link from the `MOBILE` section is intended to be used to indicated to our system that the Referrer accessed the referral program from a mobile device and shared their referral with their friend using Whatsapp. More information about available [Engagement Mediums](/success/touchpoints/) and [Share Mediums](/success/share-options/) can be found in our success center.

        Additionally, a clean share link is provided. If the given link is a vanity link, then the clean share link will have no encoding, for example `http://example.com/free`. The clean share link will be the `UNKNOWN` Share Medium and `UNKNOWN` Engagement Medium link.

        Share links work by dropping a tracking cookie in the user's browser when the user clicks the link and is directed to your referral program's landing page. This cookie includes the referral code of the Referrer that shared it. Once on your website this cookie can be read using the squatch.js [autofill](/developer/squatchjs/v2/#3-autofill-the-referral-code) method and is also automatically picked up by our squatch.js library to connect referrals.

        The referral code is also passed along to your referral program landing page as the URL parameter `rsCode`. For example `http://ssqt.co/pZVp` redirects to `https://www.google.ca/?rsCode=JOHNDOE`.
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: accountId
          in: path
          description: The ID of the account to look up
          required: true
          type: string
        - name: userId
          in: path
          description: Filters share urls by `user.id`.
          required: true
          type: string
        - name: engagementMedium
          in: query
          description: Filters share urls by `engagementMedium`.
          required: false
          type: string
        - name: shareMedium
          in: query
          description: Filters share urls by `shareMedium`.
          required: false
          type: string
        - name: programId
          in: query
          description: The ID of the program
          required: false
          type: string
      responses:
        200:
          description: A list of share urls
          schema:
            $ref: "#/definitions/Shareurls"
          examples:
            "application/json":
              $ref: "#/definitions/Shareurls/example"
        401:
          description: Unauthorized
          schema:
            $ref: "#/definitions/Error"
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Account not found
          schema:
            $ref: "#/definitions/Error"

  "/{tenant_alias}/open/user":
    get:
      summary: Get a user by a referral code
      operationId: openGetUserByCode
      x-docs-anchor: open_get_user_by_code
      tags:
        - User
        - Open Endpoint
      security: [] # Unauthenticated
      description: |
        Looks up a user based upon their `ReferralCode` and returns their personal information. This method is useful for retrieving the user when only the Referral Code is available, for example when a referred user enters a Referral Code during checkout and you want to find out who this Referral Code belongs to.

        This is an [Open Endpoint](../openendpoints/) and disabled by default. Contact support to enable the open endpoints.
      parameters:
        - name: referralCode
          in: query
          description: The code with which to lookup the user, E.g. "BOBTESTERSON". This can be a user's primary or non primary referral code.
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Found user
          schema:
            $ref: "#/definitions/UserByCode"
          examples:
            application/json:
              id: "876343"
              accountId: "613611"
              firstName: Bob
              lastInitial: T
              referralCode: BOBTESTERSON
              imageUrl: ""
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/Error"

  "/{tenant_alias}/open/code/{referral_code}":
    get:
      summary: Lookup a referral code
      operationId: openValidateCode
      x-docs-anchor: open_validate_code
      tags:
        - Referral Code
        - Open Endpoint
      security: [] # Unauthenticated
      description: |
        Looks up a referral code and the details of the attached reward.

        This is an [Open Endpoint](../openendpoints/) and disabled by default. Contact support to enable the open endpoints.
      parameters:
        - name: referral_code
          in: path
          description: The code to be validated, E.g. "BOBTESTERSON". This can be a user's primary or non primary referral code.
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Referral code found
          examples:
            "application/json":
              code: "BOBTESTERSON"
              dateCreated: 1411600868797
              programId: "referral-a"
              referrerName: "Bob T"
              reward:
                $ref: "#/definitions/RewardTemplate/example/CREDIT"
          schema:
            $ref: "#/definitions/CodeClassicReward"
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/Error"

  "/{tenant_alias}/open/code/{code}/account/{accountId}/user/{userId}":
    post:
      summary: Apply a referral code
      operationId: openApplyCode
      x-docs-anchor: open_apply_code
      tags:
        - Referral Code
        - Open Endpoint
      security:
        - APIKey: []
        - UserJWT: []
      description: |
        Apply a `ReferralCode` to a referred account to attribute a referral.

        This endpoint requires a [write token](../openendpoints/) or an API key.

        This is an [Open Endpoint](../openendpoints/) and disabled by default. Contact support to enable the open endpoints.
      parameters:
        - name: code
          in: path
          description: "Referral code to apply to user account."
          required: true
          type: string
        - name: accountId
          in: path
          description: 'Account to apply referral code to. This account will be marked as "referred by" the owner of the `referral_code`'
          required: true
          type: string
        - name: userId
          in: path
          description: 'User to apply referral code to. This user will be marked as "referred by" the owner of the `referral_code`'
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Referral code applied
          examples:
            "application/json":
              code: "BOBTESTERSON"
              dateCreated: 1411600868797
              programId: "referral-a"
              referrerName: "Bob T"
              reward:
                type: "PCT_DISCOUNT"
                discountPercent: 10
                monthsDiscountIsValid: 12
          schema:
            $ref: "#/definitions/Code"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/Error"
        401:
          description: Unauthorized
          schema:
            $ref: "#/definitions/Error"
        403:
          description: Endpoint disabled
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/Error"
  "/{tenant_alias}/open/referrals":
    get:
      summary: List referrals
      operationId: openListReferrals
      x-docs-anchor: open_list_referrals
      tags:
        - Referral
        - Open Endpoint
      security:
        - APIKey: []
        - UserJWT: []
      description: |
        Lists all of the referrals involving the given user. This method is the primary way of getting a list of everyone that has made a referral and everyone that has been referred, and supports pagination using the parameters for `limit` and `offset` to iterate through a very large list of records.

        **Note:** Either the `referringAccountId` and `referringUserId` or `referredAccountId` and `referredUserId` parameters are required, along with a [read token](../openendpoints/) for authenticaion.

        This is an [Open Endpoint](../openendpoints/) and disabled by default. Contact support to enable the open endpoints.
      parameters:
        - name: referringAccountId
          in: query
          type: string
          description: "When included, filters the results to only include referrals where this `AccountId` was the Referrer."
        - name: referringUserId
          in: query
          type: string
          description: "When included, filters the results to only include referrals where this `UserId` was the Referrer."
        - name: referredAccountId
          in: query
          type: string
          description: "When included, filters the results to only include referrals where this `AccountId` was the Referred User."
        - name: referredUserId
          in: query
          type: string
          description: "When included, filters the results to only include referrals where this `UserId` was the Referred User."
        - name: dateReferralStarted
          in: query
          type: string
          description: "When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that started between 0 and 123412451."
        - name: dateReferralPaid
          in: query
          type: string
          description: "When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that converted between 0 and 123412451."
        - name: dateReferralEnded
          in: query
          type: string
          description: "When included, filters the results either to the exact timestamp if only one value is given, or a range if devided by a comma. I.E. 0,123412451 gives all referrals that ended between 0 and 123412451."
        - name: referredModerationStatus
          in: query
          type: string
          description: "When included, filters the result to only include referred users with that status. Statuses that are accepted: `PENDING`, `APPROVED` or `DENIED`."
        - name: referrerModerationStatus
          in: query
          type: string
          description: "When included, filters the result to only include referrers with that status. Statuses that are accepted: `PENDING`, `APPROVED` or `DENIED`."
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: A list of referrals
          schema:
            $ref: "#/definitions/ReferralList"
          examples:
            "application/json":
              count: 2
              totalCount: 4
              referrals:
                - $ref: "#/definitions/Referral/example"
                - $ref: "#/definitions/Referral/example"
                # -
                #   id: "5462600de4b09b1c41108f28"
                #   referredUser:
                #     $ref: "#/definitions/User/example"
                #   referrerUser:
                #     $ref: "#/definitions/User/example"
                #   referredReward:
                #     $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
                #   referrerReward: null
                #   moderationStatus: "ACTIONED"
                #   dateReferralStarted: 1415733261238
                #   dateReferralPaid: null
                #   dateReferralEnded: null
                #   dateModerated: 1427410131006
                #   referredModerationStatus: "APPROVED"
                #   referrerModerationStatus: "APPROVED"
                # -
                #   id: "546270a6e4b0c1871186a920"
                #   referredUser:
                #     $ref: "#/definitions/User/example"
                #   referrerUser:
                #     $ref: "#/definitions/User/example"
                #   referredReward:
                #     $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
                #   referrerReward:
                #     $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
                #   moderationStatus: "ACTIONED"
                #   dateReferralStarted: 1415737510411
                #   dateReferralPaid: 1415737557217
                #   dateReferralEnded: null
                #   dateModerated: 1427410131029
                #   referredModerationStatus: "APPROVED"
                #   referrerModerationStatus: "APPROVED"
                #   fraudSignals:
                #     ip:
                #       message: "Referrer and referred came from the same IP"
                #       score: 50
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/open/account/{accountId}":
    delete:
      summary: Delete an account
      operationId: openDeleteAccount
      x-docs-anchor: open_delete_account
      tags:
        - Account
        - Open Endpoint
      security:
        - APIKey: []
      description: |
        Delete an account in your SaaSquatch project. This endpoint will delete the account and all users on the account. Learn more about Accounts vs. Users in our article on [Account Structure](/shared-vs-solo-accounts/).

        To delete only a specific User on the Account use the [Delete User endpoint](#open_delete_user).

        Learn more about deleting participants within your SaaSquatch project in our article on [Participant Deletion](/features/participant-deletion)

        Include the `doNotTrack` query parameter as `true` to indicate to the SaaSquatch system that all currently-registered Users on this Account should not be able to be re-registered on the same Account. Learn more about `doNotTrack` in our article on [Participant Deletion](/features/participant-deletion)
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: accountId
          in: path
          description: The ID of the account to be deleted
          required: true
          type: string
        - name: doNotTrack
          in: query
          description: Do not track the user (this user cannot be re-registered in SaaSquatch). Learn more about `doNotTrack` in our article on [Participant Deletion](/features/participant-deletion)
          type: boolean
      responses:
        204:
          description: Account successfully deleted
        404:
          description: No account found for the provided id
          schema:
            $ref: "#/definitions/Error"

  "/{tenant_alias}/subscription":
    post:
      summary: Create a webhook subscription
      operationId: createWebhook
      x-docs-anchor: create_webhook
      tags:
        - Webhook
      security:
        - APIKey: []

      description: |
        Subscribes a URL to receive events via webhooks
      parameters:
        - name: endpoint
          in: body
          description: Details of the endpoint to be created
          schema:
            $ref: "#/definitions/WebhookEndpoint"
        - $ref: "#/parameters/tenant_alias"
      responses:
        201:
          description: Webhook endpoint created
        default:
          $ref: "#/responses/GeneralError"
    get:
      summary: List webhook subscriptions
      operationId: listWebhooks
      x-docs-anchor: list_webhooks
      tags:
        - Webhook
      security:
        - APIKey: []

      description: |
        Lists all the URLs that are currently subscribed to receive events via webhooks
      parameters:
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: A list of endpoints
          schema:
            type: array
            items:
              $ref: "#/definitions/WebhookEndpoint"
          examples:
            "application/json":
              - endpointUrl: "https://example.com/hook"
                name: "Zapier"
              - endpointUrl: "https://another.example.com/hook"
                name: "Example"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/subscription/{url}":
    delete:
      summary: Delete a webhook subscription
      operationId: deleteWebhook
      x-docs-anchor: delete_webhook
      tags:
        - Webhook
      security:
        - APIKey: []

      description: |
        Removes a URL from receiving events via webhooks
      parameters:
        - name: url
          in: path
          description: |
            The url of the endpoint that will be removed. *Remember to URL-encode this field*
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        204:
          description: Endpoint deleted
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/subscription/{url}/test":
    post:
      summary: Test a webhook subscription
      operationId: testWebhook
      x-docs-anchor: test_webhook
      tags:
        - Webhook
      security:
        - APIKey: []
      description: |
        Sends a test event to the specified webhook
      parameters:
        - name: url
          in: path
          description: |
            The url of the endpoint to send a test message to. *Remember to URL-encode this field*
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        204:
          description: Test message sent
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/export":
    post:
      summary: Create an Export
      operationId: createExport
      x-docs-anchor: create_export
      tags:
        - Export
      security:
        - APIKey: []

      description: |
        Creates an asynchronous request for an Exports. Depending on the size of the Export and other exports in the export pipeline, it may take awhile for an
        export request to complete. Once the Export is completed, it can be downloaded in the requested format (CSV or zipped XLSX) using the download url endpoint.

        Here are a few ways to check for when an export is ready.

        - **Polling** - While an export is being prepared you can check the status using the `id`. Make sure you store the `id` of the export when you request it.
        - **Webhooks** - When an export is complete, a webhook event will be fired. Make sure you create a webhook endpoint subscription before you create your export.
        - **Listing** - You can use the API to list recent exports, and check their status.

      parameters:
        - name: export
          in: body
          description: Details of the export to be created
          schema:
            $ref: "#/definitions/ExportStub"
        - $ref: "#/parameters/tenant_alias"
      responses:
        201:
          description: Export created
          schema:
            $ref: "#/definitions/Export"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/export/{exportId}":
    get:
      summary: Lookup an Export
      operationId: getExport
      x-docs-anchor: get_export
      tags:
        - Export
      security:
        - APIKey: []
      description: |
        Looks up an Export to check its status. Useful when you're generating exports to check when an export is complete. When the status is no longer `PENDING`
        so that you can begin to download the export.
      parameters:
        - name: exportId
          in: path
          type: string
          required: true
          description: The `id` of the export to look up
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Export found
          schema:
            $ref: "#/definitions/Export"
        404:
          description: Export NOT found
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/export/{exportId}/download":
    get:
      summary: Download an Export
      operationId: downloadExport
      x-docs-anchor: download_export
      tags:
        - Export
      security:
        - APIKey: []
      description: |
        The endpoint to download a completed export. This method can only be used when an export is `COMPLETED`. Exports are not always immediately available to download
        after they have been created, often exports are large files that take time to process and prepare. If you want to check if an export is ready to be downloaded,
        use the API method to lookup an export or to list exports.
      produces:
        - "text/csv" ## CSV file downloads
      parameters:
        - name: exportId
          in: path
          type: string
          required: true
          description: The `id` of the export to look up
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Export ready
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/export/history/list":
    get:
      summary: List Exports
      operationId: listExports
      x-docs-anchor: list_exports
      tags:
        - Export
      security:
        - APIKey: []
      description: |
        List all of the exports in a tenant. Useful for tracking down exports
      parameters:
        - name: limit
          in: query
          type: integer
          default: 10
          description: A limit on the maximum number of results to return, defaults to `10`.
        - name: offset
          in: query
          type: integer
          default: 0
          description: The row number of the first result to return, defaults to `0`.
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: List of Exports found
          schema:
            $ref: "#/definitions/ExportList"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/theme/variables/schema":
    get:
      summary: Lookup variables schema
      operationId: getVariablesSchema
      x-docs-anchor: lookup_variables_schema
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []
      description: |
        Returns the variables schema object that is defined in the tenant theme repository.
        This will be a [JSON Schema](http://json-schema.org/) standards compliant definition.

        For the list of current variable values, see the [theme variables](/themes/variables/) for more info.
      produces:
        - "application/schema+json"
      parameters:
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Variables Schema Found
          schema:
            $ref: "#/definitions/VariablesSchema"
          examples:
            "application/schema+json":
              $ref: "#/definitions/VariablesSchema/example"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/theme/variables/instance":
    get:
      summary: Lookup Default Variables Values
      operationId: lookupVariables
      x-docs-anchor: lookup_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []

      description: |
        Returns the current default variables values stored for the schema object that is defined in the tenant theme repository.
      produces:
        - "application/json"
      parameters:
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Variables Found
          schema:
            $ref: "#/definitions/VariablesInstance"
          examples:
            "application/schema+json":
              $ref: "#/definitions/VariablesInstance/example"
        default:
          $ref: "#/responses/GeneralError"

    put:
      summary: Replace Default Variable Values
      operationId: replaceVariables
      x-docs-anchor: replace_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []

      description: |
        Replaces all of the previously set default variables values. Use this operation only when your
        goal is to completely replace all variable values, including deleting previous
        values of othe fields that you're not setting. Prefer to use a `PATCH` request
        when you only want to update one variable or a subset of variables.
        See [theme variables](/themes/variables/) for more info.
      parameters:
        - name: instance
          in: body
          description: The variables object to replace all previously stored default values.
          schema:
            $ref: "#/definitions/VariablesInstance"
        - $ref: "#/parameters/tenant_alias"
      responses:
        204:
          description: Variables Replaced
        400:
          $ref: "#/responses/VariablesErrorResponse"
        default:
          $ref: "#/responses/GeneralError"

    patch:
      summary: Update Default Variable Values
      operationId: updateVariables
      x-docs-anchor: update_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []
      description: |
        Updates the previously stored values for the default variables included in this request.
        Will not override, nullify or delete the other variable values that are not included.
        This method can be used to selectively set a single variable. See [theme variables](/themes/variables/) for more info.
      parameters:
        - name: instance
          in: body
          description: The variables object that will update fields included here.
          schema:
            $ref: "#/definitions/VariablesInstance"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Variables Updated
          schema:
            $ref: "#/definitions/VariablesInstance"
          examples:
            "application/json":
              $ref: "#/definitions/VariablesInstance/example"
        400:
          $ref: "#/responses/VariablesErrorResponse"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/theme/{locale}/variables/instance":
    get:
      summary: Lookup Localized Variables Values
      operationId: lookupLocaleVariables
      x-docs-anchor: lookup_locale_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []

      description: |
        Returns the current variables values, for a specific locale, stored for the schema object that is defined in the tenant theme repository.
      produces:
        - "application/json"
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: locale
          in: path
          description: The [Locale](/themes/internationalization/) for the variables object being retrieved.
          required: true
          type: string
      responses:
        200:
          description: Variables Found
          schema:
            $ref: "#/definitions/VariablesInstance"
          examples:
            "application/schema+json":
              $ref: "#/definitions/VariablesInstance/example"
        default:
          $ref: "#/responses/GeneralError"

    put:
      summary: Replace Localized Variable Values
      operationId: replaceLocaleVariables
      x-docs-anchor: replace_locale_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []

      description: |
        Replaces all of the previously set variables values for a specific locale. Use this operation only when your
        goal is to completely replace all variable values for a locale, including deleting previous
        values of othe fields that you're not setting. Prefer to use a `PATCH` request
        when you only want to update one variable or a subset of variables.
        See [theme variables](/themes/variables/) for more info.
      parameters:
        - name: instance
          in: body
          description: The variables object to replace all previously stored values.
          schema:
            $ref: "#/definitions/VariablesInstance"
        - name: locale
          in: path
          description: The [Locale](/themes/internationalization/) of the variables object being replaced.
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        204:
          description: Variables Replaced
        400:
          $ref: "#/responses/VariablesErrorResponse"
        default:
          $ref: "#/responses/GeneralError"

    patch:
      summary: Update Localized Variable Values
      operationId: updateLocaleVariables
      x-docs-anchor: update_locale_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []
      description: |
        Updates the previously stored values for the localized variables included in this request.
        Will not override, nullify or delete the other variable values that are not included.
        This method can be used to selectively set a single variable. See [theme variables](/themes/variables/) for more info.
      parameters:
        - name: instance
          in: body
          description: The variables object that will update fields included here.
          schema:
            $ref: "#/definitions/VariablesInstance"
        - name: locale
          in: path
          description: The [Locale](/themes/internationalization/) of the variables object being updated.
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Variables Updated
          schema:
            $ref: "#/definitions/VariablesInstance"
          examples:
            "application/json":
              $ref: "#/definitions/VariablesInstance/example"
        400:
          $ref: "#/responses/VariablesErrorResponse"
        default:
          $ref: "#/responses/GeneralError"

    delete:
      summary: Delete Localized Variable Values
      operationId: deleteLocaleVariables
      x-docs-anchor: delete_locale_variables
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []
      description: |
        Delete all variables for a specified locale. See [theme variables](/themes/variables/) for more info.
      parameters:
        - name: locale
          in: path
          description: The [Locale](/themes/internationalization/) of the variables object to delete.
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Variables Deleted
          schema:
            $ref: "#/definitions/VariablesInstance"
          examples:
            "application/json":
              $ref: "#/definitions/VariablesInstance/example"
        400:
          $ref: "#/responses/VariablesErrorResponse"
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/theme/email/{email_type}/preview":
    post:
      summary: Preview Theme Email
      operationId: previewThemeEmail
      x-docs-anchor: preview_theme_email
      tags:
        - Theme
        - Classic Only
      security:
        - APIKey: []

      description: |
        Generates preview content for a themed email. If the `sendTo` parameter is set this content will be sent to the provided *email address* otherwise the content will be returned in the response.
      produces:
        - "text/html"
      parameters:
        - $ref: "#/parameters/tenant_alias"
        - name: email_type
          in: path
          description: |
            The type of email to be previwed. E.g. `REFERRAL_STARTED` or `REFERRAL_CONVERTED`, see *theme mappings* in [email theming](/themes/emails/) for details.
          type: string
          required: true
        - name: locale
          in: query
          description: |
            The user locale, used for [Internationalization](/themes/internationalization).
          type: string
        - name: sendTo
          in: query
          description: |
            If an *email address* is set in the `sendTo` parameter the *preview email content* will be delivered to the provided address.
          type: string
      responses:
        200:
          description: Preview Response
          examples:
            "text/html": <html>
              <head>
              ...
              </head>
              <body>
              <h1>Congratulations Mike</h1>
              Your friend John has accepted your referral. You will now receive 10% off your next bill.
              ...
              </body>
              </body>
        204:
          description: SendTo Response
        default:
          $ref: "#/responses/GeneralError"

  "/{tenant_alias}/discount/{code}":
    get:
      deprecated: true
      summary: Lookup a discount code
      operationId: getDiscountCoupon
      x-docs-anchor: get_coupon
      tags:
        - Discount
        - Classic Only
        - Deprecated
      security:
        - APIKey: []
      description: |
        This method lets you look up the details of a referral code and to ensure that it is valid. Works with `PCT_DISCOUNT`
      parameters:
        - name: code
          in: path
          description: The coupon/referral code to look up. Eg. BOBTESTERSON
          required: true
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Information about the coupon/referral code
          examples:
            "application/json":
              "couponCode": "BOBTESTERSON"
              "discountPercentage": 20
              "dateCreated": 1377727546528
              "discountId": "saasquatch_discount"
          schema:
            $ref: "#/definitions/DiscountCode"
        404:
          description: Coupon/referral code not found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/discount":
    post:
      deprecated: true
      summary: Set discount code on an account
      operationId: setCoupon
      x-docs-anchor: set_coupon
      tags:
        - Discount
        - Classic Only
        - Deprecated
      security:
        - APIKey: []
      description: |
        This method associates a new account with their referrer. Use this method when
        someone signs up for a paid account to set the coupon code used for them. For Stripe and Recurly do not use this call.
        Instead during sign-up, just pass the coupon/referral code in your subcribe call. Works with `PCT_DISCOUNT`
      parameters:
        - name: accountDiscount
          in: body
          description: Account discount details to be updated
          schema:
            $ref: "#/definitions/AccountDiscountRequest"
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Account updated
        400:
          description: Not implemented
        default:
          $ref: "#/responses/GeneralError"
  "/{tenant_alias}/account/{accountId}/discount":
    get:
      deprecated: true
      summary: Lookup an account discount
      operationId: getAccountDiscount
      x-docs-anchor: get_account_reward
      tags:
        - Discount
        - Classic Only
        - Deprecated
      security:
        - APIKey: []

      description: |
        This method information about an account's discount, if any, and what that discount would look like with a `couponCode` applied. Works with `PCT_DISCOUNT`
      parameters:
        - name: accountId
          in: path
          description: The account to look up
          required: true
          type: string
        - name: couponCode
          in: query
          description: When included, will return a total reward available including any coupon code.
          type: string
        - $ref: "#/parameters/tenant_alias"
      responses:
        200:
          description: Information about the account discount
          examples:
            "application/json":
              "accountId": "SV0TYE5OWI11120144"
              "discountPercentage": 10
              "referrerDiscountPercent": 0
              "referredDiscountPercent": 10
              "discountId": "saasquatch_discount"
          schema:
            $ref: "#/definitions/AccountDiscount"
        404:
          description: Account not found
          schema:
            $ref: "#/definitions/Error"
        default:
          $ref: "#/responses/GeneralError"

definitions:
  ## General object details
  Account:
    required:
      - id
      - subscription
    properties:
      id:
        type: string
        description: Unique identifier for the account
        example: abc123
      subscription:
        $ref: "#/definitions/AccountSubscription"
      referral:
        $ref: "#/definitions/AccountReferral"
      currency:
        type: string
        example: USD
        description: |
          Default is `"USD"`. Otherwise use an ISO 4217 Standard currency code in uppercase.
  AccountDiscount:
    description: Information about the account's discount, if any
    properties:
      accountId:
        type: string
        example: SV0TYE5OWI11120144
        description: The account id
      discountPercentage:
        type: integer
        example: 10
        description: |
          An integer representing the total discount percentage from the referral program.
          e.g. For 10% would return the number 10. `discountPercentage` = `referredDiscountPercent` + `referrerDiscountPercent`
      referredDiscountPercent:
        type: integer
        description: |
          An integer representing the discount percentage from being referred.
          This will only have a value if the account has a coupon/referral code already associated with it, or if `couponCode` was passed as an argument.
      referrerDiscountPercent:
        type: integer
        description: An integer representing the discount earned from referring other accounts.
      ratePlanId:
        type: string
        description: |
          **Zuora only** The Zuora rate plan ID used to apply the discount.
      discountId:
        type: string
        description: |
          **Braintree only** The Braintree discount ID used to apply the discount.
      referrerName:
        type: string
        description: |
          The first and last name of the referrer that referred the user or `null` if this account was not referred.

  AccountSubscription:
    description: An object describing the current subscription for this account
    required:
      - status
    properties:
      status:
        type: string
        description: "The status of the subscription."
        example: PAID
        enum:
          - PAID
          - TRIAL
          - FREE
          - CANCELLED
      billingIntervalType:
        type: string
        description: "Type of billing interval. <br>Required when `status: PAID`. <br>Use a placeholder value of `DAY` for Referral SaaSquatch programs with non-CPA billing"
        example: DAY
        enum:
          - DAY
          - WEEK
          - MONTH
          - QUARTER
          - SEMI_ANNUAL
          - YEAR
      billingIntervalValue:
        type: integer
        description: "The value of billing interval. <br>Required when `status: PAID`. <br>Use a placeholder value of `1` for Referral SaaSquatch programs with non-CPA billing"
        example: 1
      value:
        type: number
        format: double
        example: 1
        description: "Dollar value of the subscription per renewal. <br>Required when `status: PAID`. <br>Use a placeholder value of `1` for Referral SaaSquatch programs with non-CPA billing"
  AccountReferral:
    description: Info about who referred this account. Use this on first signup.
    properties:
      code:
        type: string
        example: BOBTESTERSON
        description: |
          The referral code of the person that referred this account. Use squatch.js autofill to retrieve this value from the tracking cookie on your checkout form.
  Code:
    description: A referral code, details of the person who it belongs to, and details of the reward it unlocks
    properties:
      code:
        type: string
        example: BOBTESTERSON
        description: |
          The unique identifier for the code. E.g. "BOBTESTERSON"
      dateCreated:
        type: integer
        example: 1411600868797
        description: The date the code was created.
      programId:
        description: The ID of the program that the provided code belongs to.
        type: string
        example: my-program-id
      referrerName:
        type: string
        example: Bob Testerson
        description: |
          The name of the owner of this code. E.g. "Bob Testerson"
      reward:
        $ref: "#/definitions/RewardTemplate"
  CodeClassicReward:
    description: A referral code, details of the person who it belongs to, and details of the reward it unlocks
    properties:
      code:
        type: string
        example: BOBTESTERSON
        description: |
          The unique identifier for the code. E.g. "BOBTESTERSON"
      dateCreated:
        type: integer
        example: 1411600868797
        description: The date the code was created.
      programId:
        description: The ID of the program that the provided code belongs to.
        type: string
        example: my-program-id
      referrerName:
        type: string
        example: Bob Testerson
        description: |
          The name of the owner of this code. E.g. "Bob Testerson"
      reward:
        $ref: "#/definitions/ClassicRewardTemplate"
  DiscountCode:
    description: Information about the coupon/referral code
    properties:
      couponCode:
        type: string
        description: The coupon/referral code
        example: "BOBTESTERSON"
      referrerName:
        type: string
        description: The full name of the referrer who owns this code.
        example: "Bob Testerson"
      discountPercentage:
        type: integer
        example: 10
        description: |
          An integer representing the discount percentage. e.g. For 10% would return the number 10.
      dateCreated:
        type: integer
        example: 1377727546528
        description: "Timestamp - The coupon/referral code to look up"
      ratePlanId:
        type: string
        description: Zuora only The Zuora rate plan ID used to apply this coupon.
      discountId:
        type: string
        example: saasquatch_discount
        description: Braintree only The Braintree discount ID used to apply this coupon.

  RewardTemplate:
    description: "Details of the reward that could be earned -- but *is not yet earned*."
    properties:
      type:
        type: string
        example: CREDIT
        description: "The type of reward."
        enum:
          - PCT_DISCOUNT
          - FUELTANK
          - CREDIT
          - INTENGRATION
      unit:
        type: string
        example: cents
        description: |
          An identifier for the unit of the reward. E.g. "credit-in-cents", "freemb", "giftcard20", "tshirt", "freemonth". Only works with `CREDIT`
      credit:
        type: integer
        example: 2000
        description: |
          The amount of credit that this referral code is valid for. e.g. for $20 this
          object would have credit=2000, unit="cents". Only works for `CREDIT`
      discountPercent:
        type: integer
        description: |
          The percent discount that the referral code is valid for. E.g. "10" for "10%". Only works with `PCT_DISCOUNT`
      monthsDiscountIsValid:
        type: integer
        description: "When this reward is set to expire.  Only works with `PCT_DISCOUNT`"
      valueInCents:
        type: integer
        description: "The value of the reward in cents. Works with: `INTEGRATION`"
      rewardDetails:
        type: string
        description: "JSON object containing details about the reward. Works with: `INTEGRATION`"
    example:
      CREDIT:
        type: "CREDIT"
        unit: "CENTS"
        credit: 2500
      PCT_DISCOUNT:
        type: "PCT_DISCOUNT"
        discountPercent: 20
        unit: "%"

  ClassicRewardTemplate:
    description: |
      <span class="label">Classic Only</span>
      Details of the reward that could be earned -- but *is not yet earned*.
    properties:
      type:
        type: string
        example: CREDIT
        description: "The type of reward."
        enum:
          - PCT_DISCOUNT
          - FUELTANK
          - CREDIT
          - INTENGRATION
      unit:
        type: string
        example: cents
        description: |
          An identifier for the unit of the reward. E.g. "credit-in-cents", "freemb", "giftcard20", "tshirt", "freemonth". Only works with `CREDIT`
      credit:
        type: integer
        example: 2000
        description: |
          The amount of credit that this referral code is valid for. e.g. for $20 this
          object would have credit=2000, unit="cents". Only works for `CREDIT`
      discountPercent:
        type: integer
        description: |
          The percent discount that the referral code is valid for. E.g. "10" for "10%". Only works with `PCT_DISCOUNT`
      monthsDiscountIsValid:
        type: integer
        description: "When this reward is set to expire.  Only works with `PCT_DISCOUNT`"
      valueInCents:
        type: integer
        description: "The value of the reward in cents. Works with: `INTEGRATION`"
      rewardDetails:
        type: string
        description: "JSON object containing details about the reward. Works with: `INTEGRATION`"
    example:
      CREDIT:
        type: "CREDIT"
        unit: "CENTS"
        credit: 2500
      PCT_DISCOUNT:
        type: "PCT_DISCOUNT"
        discountPercent: 20
        unit: "%"

  NewReward:
    description: Details of a new reward to create.
    properties:
      type:
        type: string
        description: "The type of reward."
        example: PCT_DISCOUNT
        enum:
          - PCT_DISCOUNT
          - CREDIT
          - FUELTANK
      dateExpires:
        type: integer
        description: "Timestamp of when this reward is set to expire."
        example: 1471028988000
      dateScheduledFor:
        type: integer
        description: "Timestamp of when the reward is sheduled to become available."
      cancellable:
        type: boolean
        description: "If a reward is cancellable then it may be revoked. If it has been cancelled then dateCancelled will be non-null."
        example: true
      unit:
        type: string
        description: "An identifier for the unit of the reward. E.g. `'credit-in-cents'`, `'freemb'`, `'giftcard20'`, `'tshirt'`, `'freemonth'` or `'%'`. Works with: `CREDIT`"
      discountPercent:
        type: integer
        description: "The percent discount. E.g. 10 means 10% Works with: `PCT_DISCOUNT`"
        example: 15
      assignedCredit:
        type: integer
        description: "The earned quantity of the reward. Works with: `CREDIT`"
      currency:
        type: string
        description: "For programs that require a currency. Works with: `CREDIT`"
      fuelTankType:
        type: string
        description: "The type of reward associated with this fueltank code. Works with: `FUELTANK`"
        enum:
          - PCT_DISCOUNT
          - CREDIT
      fuelTankCode:
        type: string
        description: "The fueltank code associated with this reward. Works with: `FUELTANK`."
      amount:
        type: integer
        description: "The earned quantity of the reward. Works with: `FUELTANK`"

  RewardList:
    type: object
    description: A list of Reward objects as `rewards`
    properties:
      rewards:
        type: array
        description: A list of Reward objects. This is the actual data in this list envelope.
        items:
          $ref: "#/definitions/Reward"

  Reward:
    title: A Reward object.
    description: Rewards are used in SaaSquatch to track the credits, discounts, gift cards and other prizes that a User earns.
    properties:
      id:
        type: string
        description: The unique identifier for this reward
      type:
        type: string
        description: "The type of reward."
        enum:
          - PCT_DISCOUNT
          - CREDIT
          - FUELTANK
      dateGiven:
        type: integer
        description: "Timestamp of when this reward was earned."
      dateExpires:
        type: integer
        description: "Timestamp of when this reward is set to expire."
      dateCancelled:
        type: integer
        description: "Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled."
      dateScheduledFor:
        type: integer
        description: "Timestamp of when the reward is sheduled to become available."
      cancellable:
        type: boolean
        description: "If a reward is cancellable then it may be revoked. If it has been cancelled then `dateCancelled` will be non-null."
      rewardSource:
        type: string
        description: "The type of the source of the reward."
        enum:
          - FRIEND_SIGNUP
          - REFERRED
          - MANUAL
      unit:
        type: string
        description: "An identifier for the unit of the reward. E.g. `'credit-in-cents'`, `'freemb'`, `'giftcard20'`, `'tshirt'`, `'freemonth'` or `'%'`"
      discountPercent:
        type: integer
        description: "The percent discount. E.g. 10 means 10% Works with: `PCT_DISCOUNT`"
      name:
        type: string
        description: "The human-readable name of the reward."
      description:
        type: string
        description: "The human-readable description of the reward. Works with: `INTEGRATION`"
      assignedCredit:
        type: integer
        description: "The earned quantity of the reward. Works with: `CREDIT`"
      redeemedCredit:
        type: integer
        description: "The redeemed quantity of the reward. Works with: `CREDIT`"
      redemptions:
        type: array
        items:
          $ref: "#/definitions/Redemption"
      currency:
        type: string
        description: "For programs that require a currency. Works with: `CREDIT`"
      amount:
        type: integer
        description: "The earned quantity of the reward. Works with: `FUELTANK`"
      fuelTankCode:
        type: string
        description: "The fueltank code associated with this reward. Works with: `FUELTANK`"
      fueltankType:
        type: string
        description: "The type of reward associated with this fueltank code. Works with: `FUELTANK`"
        enum:
          - PCT_DISCOUNT
          - CREDIT
    example:
      PCT_DISCOUNT:
        id: "5462600de4b09b1c41108f2e"
        type: "PCT_DISCOUNT"
        dateGiven: 1415733261275
        dateExpires: null
        dateCancelled: null
        accountId: "613611"
        userId: "876343"
        cancellable: true
        rewardSource: "REFERRED"
        discountPercent: 20
        unit: "%"
      CREDIT:
        id: "582142aae4b05442a5fa01a5"
        type: "CREDIT"
        dateGiven: 1478574762838
        dateExpires: null
        dateCancelled: null
        dateScheduledFor: null
        accountId: "613611"
        userId: "876343"
        cancellable: true
        rewardSource: "REFERRED"
        unit: "CENTS"
        assignedCredit: 2500
        redeemedCredit: 0
        redemptions:
          - $ref: "#/definitions/Redemption/example"
        name: "Dollar Credit"
        currency: null
      FUELTANK:
        id: "12345678e4b1234aff143be5"
        type: "FUELTANK"
        dateGiven: 1497907329060
        dateExpires: null
        dateCancelled: null
        accountId: "abc_122"
        userId: "abc_122"
        cancellable: true
        rewardSource: "FRIEND_SIGNUP"
        fuelTankCode: "CODE8"
        unit: "CENTS"
        amount: 1000
        fueltankType: "CREDIT"

  Redemption:
    title: A redemption object
    description: "Details about when a quantity of a reward was redeemed from the SaaSquatch system."
    properties:
      id:
        type: string
        description: "The unique identifier for this redemption"
        example: "5462600de4b09b1c41238f2f"
      dateRedeemed:
        type: integer
        description: "Timestamp of when this redemption took place."
        example: 1415733261275
      quantityRedeemed:
        type: integer
        description: "the amount of the reward that was redeemed."
        example:
    example:
      id: "5462600de4b09b1c41238f2f"
      dateRedeemed: 1415733261275
      quantityRedeemed: 2000

  UserStub:
    title: A User object stub
    description: The basic information about a User used when you want to create a new user, called a UserStub.
    required:
      - id
      - accountId
    properties:
      id:
        type: string
        example: "219065"
        description: The unique identifier provided for this user.
      accountId:
        type: string
        example: "accc9065"
        description: The unique identifier of the Account that this user belongs to.
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      imageUrl:
        type: string
        example: "https://www.example.com/profiled/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      locale:
        type: string
        example: "`en` or `en_US` or `zh_CN`"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
    example:
      id: "898746321"
      accountId: "987321"
      email: "hello@example.com"
      firstName: "Henk"
      lastName: "Thompson"
      referralCode: "HENKTHOMPSON"
      imageUrl: ""
      locale: null

  User:
    title: The User object
    description: An object describing an individual user. Users are used in SaaSquatch to track people/contacts/leads. When a referral happens, it always happens between two Users.
    required:
      - id
      - accountId
      - firstName
    properties:
      id:
        type: string
        example: "219065"
        description: The unique identifier provided for this user.
      accountId:
        type: string
        example: "accc9065"
        description: The unique identifier of the Account that this user belongs to.
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      imageUrl:
        type: string
        example: "https://www.example.com/profiled/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      firstSeenIP:
        type: string
        readOnly: true
        example: "10.230.163.157"
        description: |
          The user's IP address on indentification
      lastSeenIP:
        type: string
        readOnly: true
        example: "184.66.242.57"
        description: |
          The user's last known IP address
      dateCreated:
        type: integer
        readOnly: true
        example: 1467222395030
        description: |
          The Unix time stamp of when the user was created
      emailHash:
        type: string
        readOnly: true
        example: "180bc1412a038746af9b37fb782724a2"
        description: |
          The hash of the user's email address
      referralSource:
        type: string
        readOnly: true
        example: "http://unifiedtestapp.herokuapp.com/"
        description: |
          The domain from which the user was registered
      locale:
        type: string
        example: "`en` or `en_US` or `zh_CN`"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
      shareLinks:
        readOnly: true
        $ref: "#/definitions/Sharelink"
    example:
      id: "898746321"
      accountId: "987321"
      email: "hello@example.com"
      firstName: "Henk"
      lastName: "Thompson"
      referralCode: "HENKTHOMPSON"
      imageUrl: ""
      firstSeenIP: "10.230.163.157"
      lastSeenIP: "184.66.242.57"
      dateCreated: 1467222395030
      emailHash: "180bc1412a038746af9b37fb782724a2"
      referralSource: "http://unifiedtestapp.herokuapp.com/"
      locale: null
      shareLinks:
        $ref: "#/definitions/Sharelink/example"

  UserPII:
    title: The User object
    description: An object containing the PII stored in the SaaSquatch system for a specific SaaSquatch user.
    required:
      - id
      - accountId
      - firstName
    properties:
      id:
        type: string
        example: "219065"
        description: The unique identifier provided for this user.
      accountId:
        type: string
        example: "accc9065"
        description: The unique identifier of the Account that this user belongs to.
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      lastInitial:
        type: string
        example: "T"
        description: |
          The user's last name initial
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      imageUrl:
        type: string
        example: "https://www.example.com/profiled/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      cookieId:
        type: string
        example: "2523423436323"
        description: A unique identifier for this participant.
      paymentProviderId:
        type: string
        example: "cus_8rVOAthabctvT6"
        description: The paymentProviderId is either the Stripe Customer ID, the Recurly Account ID, the Braintree Account ID or the Zuora Account ID. This field cannot be updated. Do not include this arguement on an API-only program, or unless looking to set it.
      locale:
        type: string
        example: "`en` or `en_US` or `zh_CN`"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
      referable:
        type: boolean
        example: true
        description: Flag used by the SaaSquatch system to determine whether a user is able to be referred.
      customFields:
        type: object
        description: |
          An object containing the custom fields for this user.

          Learn more about the available custom field functionality in our [Custom Fields Developer Guide](/features/custom-user-fields)
      firstSeenIP:
        type: string
        readOnly: true
        example: "10.230.163.157"
        description: |
          The user's IP address on indentification
      lastSeenIP:
        type: string
        readOnly: true
        example: "184.66.242.57"
        description: |
          The user's last known IP address
      firstSeenIPLocation:
        properties:
          lat:
            type: number
            format: float
            example: 48.4765
            description: |
              The latitude of the user's first seen IP address
          lon:
            type: number
            format: float
            example: -123.3145
            description: |
              The longitude of the user's first seen IP address
      lastSeenIPLocation:
        properties:
          lat:
            type: number
            format: float
            example: 48.4765
            description: |
              The latitude of the user's last known IP address
          lon:
            type: number
            format: float
            example: -123.3145
            description: |
              The longitude of the user's last known IP address
      firstSeenUserAgent:
        type: string
        readOnly: true
        example: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.146 Safari/537.36"
        description: |
          The user's browser user agent on indentification
      lastSeenUserAgent:
        type: string
        readOnly: true
        example: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.146 Safari/537.36"
        description: |
          The latest user agent seen for the user
      dateCreated:
        type: integer
        readOnly: true
        example: 1467222395030
        description: |
          The Unix time stamp of when the user was created
      emailHash:
        type: string
        readOnly: true
        example: "180bc1412a038746af9b37fb782724a2"
        description: |
          The hash of the user's email address
      referralSource:
        type: string
        readOnly: true
        example: "http://unifiedtestapp.herokuapp.com/"
        description: |
          The domain from which the user was registered
      shareLinks:
        readOnly: true
        $ref: "#/definitions/Sharelink"
      referredByReferral:
        $ref: "#/definitions/PIIReferral"
      rewards:
        properties:
          totalCount:
            type: integer
            description: The number of rewards earned by the user
          data:
            type: array
            items:
              $ref: "#/definitions/Reward"
      rewardBalances:
        type: array
        items:
          $ref: "#/definitions/RewardBalance"
      referrals:
        properties:
          totalCount:
            type: integer
            description: A list of the referrals made by the user.
          data:
            type: array
            items:
              $ref: "#/definitions/PIIReferralList"
      segments:
        type: array
        items:
          type: string
        description: A list of segments that a user is a member of.
    example:
      id: abc_132
      accountId: abc_132
      firstName: John
      lastName: Doe
      lastInitial: D
      referralCode: JOHNDOECODE
      imageUrl: ""
      email: john@example.com
      cookieId:
      paymentProviderId:
      locale:
      referable: true
      customFields: {}
      firstSeenIP: 207.194.49.162
      lastSeenIP: 207.194.49.162
      firstSeenIPLocation:
        lat: 48.4765
        lon: -123.3145
      lastSeenIPLocation:
        lat: 48.4765
        lon: -123.3145
      firstSeenUserAgent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.146 Safari/537.36
      lastSeenUserAgent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.146 Safari/537.36
      dateCreated: 1521477982534
      emailHash: d4c74594d841139328695756648b6bd6
      referralSource: UNKNOWN
      shareLinks:
        $ref: "#/definitions/Sharelink/example"
      referredByReferral:
        $ref: "#/definitions/PIIReferral/example"
      rewards:
        totalCount: 1
        data:
          - $ref: "#/definitions/Reward/example/CREDIT"
      rewardBalances:
        - $ref: "#/definitions/RewardBalance/example/CREDIT"
      referrals:
        totalCount: 1
        data:
          - $ref: "#/definitions/PIIReferral/example"
        segments: []

  RewardBalanceList:
    type: object
    description: A list of Reward Balance objects as `rewardBalances`
    properties:
      rewardBalances:
        type: array
        description: A list of Reward Balance objects. This is the actual data in this list envelope.
        items:
          $ref: "#/definitions/RewardBalance"

  RewardBalance:
    description: Details of the balance of several individual rewards.
    properties:
      type:
        type: string
        example: CREDIT
        description: "The type of reward."
        enum:
          - PCT_DISCOUNT
          - CREDIT
          - FUELTANK
      unit:
        type: string
        example: cents
        description: |
          An identifier for the unit of the reward. E.g. "credit-in-cents", "freemb", "giftcard20", "tshirt", "freemonth". Only works with `CREDIT`
      count:
        type: integer
        description: |
          "The number of rewards earned. Usually is equal to the number of successful referrals made.
          E.g. An account has $80 of credit due to the referral program. $60 from making referrals, $20 from being referred.
          The count would be 4 rewards, each worth $20. Only works for `CREDIT`"
      totalAssignedCredit:
        type: integer
        example: 4000
        description: "The total assignedCredit for all reward credits of the same unit type. Only works with types: `CREDIT`"
      totalRedeemedCredit:
        type: integer
        example: 1490
        description: "The total redeemedCredit for all reward credits of the same unit type. Only works with types: `CREDIT`"
      totalDiscountPercent:
        type: integer
        description: "The total discountPercent from all rewards. Only works with types: `PCT_DISCOUNT`"
      referredDiscountPercent:
        type: integer
        description: "The total discountPercent from rewards with `rewardSource = REFERRED` Only works with types: `PCT_DISCOUNT`"
      referrerDiscountPercent:
        type: integer
        description: "The total discountPercent from rewards with `rewardSource = FRIEND_SIGNUP` Only works with types: `PCT_DISCOUNT`"
      totalFuelTankCodes:
        type: integer
        description: "The number of earned fueltank rewards. Only works with type: `FUELTANK`"
    example:
      CREDIT:
        type: "CREDIT"
        count: "4"
        totalAssignedCredit: "10000"
        totalRedeemedCredit: "0"
        unit: "cents"
      PCT_DISCOUNT:
        type: "PCT_DISCOUNT"
        totalDiscountPercent: "30"
        referredDiscountPercent: "10"
        referrerDiscountPercent: "20"
      FUELTANK:
        type: "FUELTANK"
        totalFuelTankCodes: 1

  Referral:
    description: A link between the user/account of the referrer and the new referred user/account. The authoritative source of who has referred whom. Not all referrals result in a Reward or a RewardBalance being created, such as in-progress referrals.
    properties:
      id:
        type: string
        example: abdsds5124abewet
        description: Unique identifier for the Referral object
      referredUser:
        $ref: "#/definitions/User"
      referrerUser:
        $ref: "#/definitions/User"
      referredReward:
        $ref: "#/definitions/Reward"
      referrerReward:
        $ref: "#/definitions/Reward"
      referralCodeUsed:
        type: string
        title: Referral Code Used
        description: "The referrers code that was used by the referred for the referral."
      shareLinkUsed:
        type: string
        title: Share Link Used
        description: "The sharelink that was used by the referred for the referral."
      moderationStatus:
        type: string
        example: PENDING
        description: |
          When referrals are manually managed, each referral has a `PENDING` state until it is explicitly moderated.
        enum:
          - PENDING
          - ACTIONED
      referredModerationStatus:
        type: string
        example: PENDING
        description: |
          Used to identify the *referred* user's moderation status and affect Reward cancellation.
        enum:
          - PENDING
          - APPROVED
          - DENIED
      referrerModerationStatus:
        type: string
        example: PENDING
        description: |
          Used to identify the *referrer* user's moderation status and affect Reward cancellation.
        enum:
          - PENDING
          - APPROVED
          - DENIED
      fraudSignals:
        $ref: "#/definitions/FraudSignals"
      dateReferralStarted:
        type: integer
        description: "Timestamp of when this referral was started."
      dateReferralPaid:
        type: integer
        description: "Timestamp of when this referral was marked as `PAID`."
      dateReferralEnded:
        type: integer
        description: "Timestamp of when this referral was ended."
      dateModerated:
        type: integer
        description: "Timestamp of when this referral was last moderated."
    example:
      id: "546270a6e4b0c1871186a920"
      referredUser:
        $ref: "#/definitions/User/example"
      referrerUser:
        $ref: "#/definitions/User/example"
      referredReward:
        $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
      referrerReward:
        $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
      referralCodeUsed: "LORETTABURKE10"
      shareLinkUsed: "http://ssqt.co/mPbcF5"
      moderationStatus: "ACTIONED"
      dateReferralStarted: 1415737510411
      dateReferralPaid: 1415737557217
      dateReferralEnded: null
      dateModerated: 1427410131029
      referredModerationStatus: "APPROVED"
      referrerModerationStatus: "APPROVED"
      fraudSignals:
        ip:
          message: "Referrer and referred came from the same IP"
          score: 50

  PIIReferral:
    description: A link between the user/account of the referrer and the new referred user/account. The authoritative source of who has referred whom. Not all referrals result in a Reward or a RewardBalance being created, such as in-progress referrals.
    properties:
      id:
        type: string
        example: abdsds5124abewet
        description: Unique identifier for the Referral object
      referredUser:
        $ref: "#/definitions/User"
      referrerUser:
        $ref: "#/definitions/User"
      referredReward:
        $ref: "#/definitions/Reward"
      referrerReward:
        $ref: "#/definitions/Reward"
      moderationStatus:
        type: string
        example: PENDING
        description: |
          When referrals are manually managed, each referral has a `PENDING` state until it is explicitly moderated.
        enum:
          - PENDING
          - ACTIONED
      referredModerationStatus:
        type: string
        example: PENDING
        description: |
          Used to identify the *referred* user's moderation status and affect Reward cancellation.
        enum:
          - PENDING
          - APPROVED
          - DENIED
      referrerModerationStatus:
        type: string
        example: PENDING
        description: |
          Used to identify the *referrer* user's moderation status and affect Reward cancellation.
        enum:
          - PENDING
          - APPROVED
          - DENIED
      fraudSignals:
        $ref: "#/definitions/FraudSignals"
      dateReferralStarted:
        type: integer
        description: "Timestamp of when this referral was started."
      dateReferralPaid:
        type: integer
        description: "Timestamp of when this referral was marked as `PAID`."
      dateReferralEnded:
        type: integer
        description: "Timestamp of when this referral was ended."
      dateModerated:
        type: integer
        description: "Timestamp of when this referral was last moderated."
    example:
      id: "546270a6e4b0c1871186a920"
      referredUser:
        $ref: "#/definitions/User/example"
      referrerUser:
        $ref: "#/definitions/User/example"
      referredReward:
        $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
      referrerReward:
        $ref: "#/definitions/Reward/example/PCT_DISCOUNT"
      moderationStatus: "ACTIONED"
      dateReferralStarted: 1415737510411
      dateReferralPaid: 1415737557217
      dateReferralEnded: null
      dateModerated: 1427410131029
      referredModerationStatus: "APPROVED"
      referrerModerationStatus: "APPROVED"
      fraudSignals:
        ip:
          message: "Referrer and referred came from the same IP"
          score: 50

  FraudSignals:
    description: Information about signals of potential fraud on the referral
    properties:
      name:
        $ref: "#/definitions/FraudSignal"
      ip:
        $ref: "#/definitions/FraudSignal"
      email:
        $ref: "#/definitions/FraudSignal"
      rate:
        $ref: "#/definitions/FraudSignal"

  FraudSignal:
    description: Information about an individual fraud signal on the referral
    properties:
      message:
        type: string
        description: "A human readable description of the fraud signal. For example: 'Referrer and referred have very similar names'"
      score:
        type: integer
        description: "A numeric score that describes the severity of the fraud signal."

  ThemeReward:
    description: Details of an individual reward.
    properties:
      dateGiven:
        type: integer
        format: int64
        description: "Timestamp of when this reward was earned."
      dateExpires:
        type: integer
        format: int64
        description: "Timestamp of when this reward is set to expire."
      dateCancelled:
        type: integer
        format: int64
        description: "Timestamp if the reward is cancellable and has been cancelled, the date it was cancelled on. Null if not never cancelled."
      unit:
        type: string
        description: "An identifier for the unit of the reward. E.g. `'credit-in-cents'`, `'freemb'`, `'giftcard20'`, `'tshirt'`, `'freemonth'` or `'%'`"
      name:
        type: string
        description: "The displayable name for the reward"
      value:
        type: integer
        description: "The value of the reward"

  ThemeReferral:
    type: object
    description: A link between the user/account of the referrer and the new referred user/account. The authoritative source of who has referred whom. Not all referrals result in a Reward or a RewardBalance being created, such as in-progress referrals.
    properties:
      id:
        type: string
        example: abdsds5124abewet
        description: Unique identifier for the Referral object
      referrerRewardDeniedOrCancelled:
        type: boolean
        description: "If this referral's referrer reward is currently in a cancelled state or has otherwise been prevented (denied) via moderation"
      referredRewardDeniedOrCancelled:
        type: boolean
        description: "If the referral's referred reward is currently in a cancelled state or has otherwise been prevented (denied) via moderation"
      referredReward:
        $ref: "#/definitions/ThemeReward"
      referrerReward:
        $ref: "#/definitions/ThemeReward"
      moderationStatus:
        type: string
        example: PENDING
        description: |
          "When referrals are manually managed, each referral has a `PENDING` state until it is explicitly moderated."
        enum:
          - PENDING
          - ACTIONED
      referredModerationStatus:
        type: string
        example: PENDING
        description: |
          "Used to identify the *referred* user's moderation status and affect Reward cancellation."
        enum:
          - PENDING
          - APPROVED
          - DENIED
      referrerModerationStatus:
        type: string
        example: PENDING
        description: |
          "Used to identify the *referrer* user's moderation status and affect Reward cancellation."
        enum:
          - PENDING
          - APPROVED
          - DENIED
      dateReferralStarted:
        type: integer
        format: int64
        description: "Timestamp of when this referral was started."
      dateReferralPaid:
        type: integer
        format: int64
        description: "Timestamp of when this referral was marked as `PAID`."
      dateReferralEnded:
        type: integer
        format: int64
        description: "Timestamp of when this referral was ended."
      dateModerated:
        type: integer
        format: int64
        description: "Timestamp of when this referral was last moderated."

  ThemeReferrerReferralDto:
    type: object
    description: "Details of a user who was referred by the current user"
    allOf:
      - $ref: "#/definitions/ThemeReferral"
      - type: object
        properties:
          referredUser:
            $ref: "#/definitions/User"

  ThemeReferredReferralDto:
    type: object
    description: "Details of who referred the current user"
    allOf:
      - $ref: "#/definitions/ThemeReferral"
      - type: object
        properties:
          referredByUser:
            $ref: "#/definitions/User"

  ProgramShareLink:
    description: Share links for a users program.
    type: object
    properties:
      cleanShareLink:
        type: string
        title: "The clean link for a given program"
        description: "If the program's primary link is a vanity link then this will be the unencoded link, if not it is the UNKNOWN engagementMedium and UNKNOWN shareMedium link."
      MOBILE:
        title: "Mobile Share Links"
        type: object
        description: "Share links tracked with the MOBILE engagement medium."
        $ref: "#/definitions/subProgramShareLink"
      EMAIL:
        title: "Email Share Links"
        type: object
        description: "Share links tracked with the EMAIL engagement medium."
        $ref: "#/definitions/subProgramShareLink"
      UNKNOWN:
        title: "Share Links"
        type: object
        description: "Share links tracked with the UNKNOWN engagement medium."
        $ref: "#/definitions/subProgramShareLink"
    example:
      fakeProgram1:
        cleanShareLink: "http://example.com/free"
        MOBILE:
          DIRECT: "http://example.com/free?me"
        EMAIL:
          DIRECT: "http://example.com/free?mP"
        UNKNOWN:
          DIRECT: "http://example.com/free?mv"

  GeneratedProgramShareLink:
    description: Auto Generated Share links for a users program.
    type: object
    properties:
      cleanShareLink:
        type: string
        title: "The clean link for a given program"
        description: "If the program's primary link is a vanity link then this will be the unencoded link, if not it is the UNKNOWN engagementMedium and UNKNOWN shareMedium link."
      MOBILE:
        title: "Mobile Share Links"
        type: object
        description: "Share links tracked with the MOBILE engagement medium."
        $ref: "#/definitions/subProgramShareLink"
      EMAIL:
        title: "Email Share Links"
        type: object
        description: "Share links tracked with the EMAIL engagement medium."
        $ref: "#/definitions/subProgramShareLink"
      UNKNOWN:
        title: "Share Links"
        type: object
        description: "Share links tracked with the UNKNOWN engagement medium."
        $ref: "#/definitions/subProgramShareLink"
    example:
      fakeProgram1:
        cleanShareLink: "http://ssqt.co/mzzxNn"
        MOBILE:
          DIRECT: "http://ssqt.co/mezxNn"
        EMAIL:
          DIRECT: "http://ssqt.co/mPzxNn"
        UNKNOWN:
          DIRECT: "http://ssqt.co/mvzxNn"

  subProgramShareLink:
    properties:
      DIRECT:
        type: string
        title: "Direct Share Link"
        description: "Share link associated with the DIRECT share medium."

  Sharelink:
    description: Share link for an individual user.
    properties:
      shareLink:
        type: string
        description: The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.
      facebookShareLink:
        type: string
        description: "The Share Link for Facebook."
      twitterShareLink:
        type: string
        description: "The Share Link for Twitter."
      emailShareLink:
        type: string
        description: "The Share Link for Email."
      mobileShareLink:
        type: string
        description: "The Share Link for mobile devices."
      mobileFacebookShareLink:
        type: string
        description: "The Share Link for Facebook on mobile devices."
      mobileTwitterSharelink:
        type: string
        description: "The Share Link for Twitter on mobile devices."
      mobileEmailShareLink:
        type: string
        description: "The Share Link for Email on mobile devices."
      EMBED:
        description: An individual user's Share links for use in EMBED.
        properties:
          shareLink:
            type: string
            description: The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.
          facebookShareLink:
            type: string
            description: "The Share Link for Facebook."
          twitterShareLink:
            type: string
            description: "The Share Link for Twitter."
          emailShareLink:
            type: string
            description: "The Share Link for Email."
          linkedinShareLink:
            type: string
            description: "The Share Link for linkedin."
      POPUP:
        description: An individual user's Share links for use in POPUP.
        properties:
          shareLink:
            type: string
            description: The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.
          facebookShareLink:
            type: string
            description: "The Share Link for Facebook."
          twitterShareLink:
            type: string
            description: "The Share Link for Twitter."
          emailShareLink:
            type: string
            description: "The Share Link for Email."
          linkedinShareLink:
            type: string
            description: "The Share Link for linkedin."
      HOSTED:
        description: An individual user's Share links for use in HOSTED.
        properties:
          shareLink:
            type: string
            description: The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.
          facebookShareLink:
            type: string
            description: "The Share Link for Facebook."
          twitterShareLink:
            type: string
            description: "The Share Link for Twitter."
          emailShareLink:
            type: string
            description: "The Share Link for Email."
          linkedinShareLink:
            type: string
            description: "The Share Link for linkedin."
      MOBILE:
        description: An individual user's Share links for use in MOBILE.
        properties:
          shareLink:
            type: string
            description: The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.
          facebookShareLink:
            type: string
            description: "The Share Link for Facebook."
          twitterShareLink:
            type: string
            description: "The Share Link for Twitter."
          emailShareLink:
            type: string
            description: "The Share Link for Email."
          linkedinShareLink:
            type: string
            description: "The Share Link for linkedin."
      EMAIL:
        description: An individual user's Share links for use in EMAIL.
        properties:
          shareLink:
            type: string
            description: The unique share link the user can refer their friends with. The Share Link contains the Referral Code for making referrals and a source for Analytics purposes.
          facebookShareLink:
            type: string
            description: "The Share Link for Facebook."
          twitterShareLink:
            type: string
            description: "The Share Link for Twitter."
          emailShareLink:
            type: string
            description: "The Share Link for Email."
          linkedinShareLink:
            type: string
            description: "The Share Link for linkedin."

    example:
      shareLink: "http://ssqt.co/mvbcF5"
      facebookShareLink: "http://ssqt.co/mmbcF5"
      twitterShareLink: "http://ssqt.co/mRbcF5"
      emailShareLink: "http://ssqt.co/mLbcF5"
      linkedinShareLink: "http://ssqt.co/mLbcF5"
      mobileShareLink: "http://ssqt.co/mebcF5"
      mobileFacebookShareLink: "http://ssqt.co/mnbcF5"
      mobileTwitterShareLink: "http://ssqt.co/mCbcF5"
      mobileEmailShareLink: "http://ssqt.co/mEbcF5"

      EMBED:
        shareLink: "http://ssqt.co/mQbcF5"
        facebookShareLink: "http://ssqt.co/mwbcF5"
        twitterShareLink: "http://ssqt.co/mcbcF5"
        emailShareLink: "http://ssqt.co/mJbcF5"
        linkedinShareLink: "http://ssqt.co/mHbcF5"

      POPUP:
        shareLink: "http://ssqt.co/m5bcF5"
        facebookShareLink: "http://ssqt.co/m9bcF5"
        twitterShareLink: "http://ssqt.co/mMbcF5"
        emailShareLink: "http://ssqt.co/mobcF5"
        linkedinShareLink: "http://ssqt.co/m7bcF5"

      HOSTED:
        shareLink: "http://ssqt.co/mtbcF5"
        facebookShareLink: "http://ssqt.co/mubcF5"
        twitterShareLink: "http://ssqt.co/mSbcF5"
        emailShareLink: "http://ssqt.co/mlbcF5"
        linkedinShareLink: "http://ssqt.co/mYbcF5"

      MOBILE:
        shareLink: "http://ssqt.co/mebcF5"
        facebookShareLink: "http://ssqt.co/mnbcF5"
        twitterShareLink: "http://ssqt.co/mCbcF5"
        emailShareLink: "http://ssqt.co/mEbcF5"
        linkedinShareLink: "http://ssqt.co/m3bcF5"

      EMAIL:
        shareLink: "http://ssqt.co/mPbcF5"
        facebookShareLink: "http://ssqt.co/mTbcF5"
        twitterShareLink: "http://ssqt.co/mGbcF5"
        emailShareLink: "http://ssqt.co/mbbcF5"
        linkedinShareLink: "http://ssqt.co/m1bcF5"

  Shareurls:
    description: Share urls for an individual user.
    properties:
      shareLinks:
        type: string
        description: The unique primary share link the user can refer their friends with. The share link contains the Referral Code for making referrals and a source for Analytics purposes.
        properties:
          cleanShareLink:
            type: string
            title: "The clean link for a given program"
            description: "If the program's primary link is a vanity link then this will be the unencoded link, if not it is the UNKNOWN engagementMedium and UNKNOWN shareMedium link."
          EMAIL:
            description: An individual user's Share links for use in the EMAIL engagementMedium.
            properties:
              EMAIL:
                type: string
                description: "The Share Link for the Email shareMedium."
              FACEBOOK:
                type: string
                description: "The Share Link for the Facebook shareMedium."
              PINTEREST:
                type: string
                description: "The Share Link for the Pinterest shareMedium."
              TWITTER:
                type: string
                description: "The Share Link for the Twitter shareMedium."
              DIRECT:
                type: string
                description: "The Share Link for the Direct shareMedium."
              WHATSAPP:
                type: string
                description: "The Share Link for the Whatsapp shareMedium."
              LINEMESSENGER:
                type: string
                description: "The Share Link for the Line Messenger shareMedium."
              SMS:
                type: string
                description: "The Share Link for the SMS shareMedium."
              FBMESSENGER:
                type: string
                description: "The Share Link for the Facebook Messenger shareMedium."
              UNKNOWN:
                type: string
                description: "The Share Link for an unknown shareMedium."
              LINKEDIN:
                type: string
                description: "The Share Link for the linkedIn shareMedium."
          MOBILE:
            description: An individual user's Share links for use in the MOBILE engagementMedium.
            properties:
              EMAIL:
                type: string
                description: "The Share Link for the Email shareMedium."
              FACEBOOK:
                type: string
                description: "The Share Link for the Facebook shareMedium."
              PINTEREST:
                type: string
                description: "The Share Link for the Pinterest shareMedium."
              TWITTER:
                type: string
                description: "The Share Link for the Twitter shareMedium."
              DIRECT:
                type: string
                description: "The Share Link for the Direct shareMedium."
              WHATSAPP:
                type: string
                description: "The Share Link for the Whatsapp shareMedium."
              LINEMESSENGER:
                type: string
                description: "The Share Link for the Line Messenger shareMedium."
              SMS:
                type: string
                description: "The Share Link for the SMS shareMedium."
              FBMESSENGER:
                type: string
                description: "The Share Link for the Facebook Messenger shareMedium."
              UNKNOWN:
                type: string
                description: "The Share Link for an unknown shareMedium."
              LINKEDIN:
                type: string
                description: "The Share Link for the linkedIn shareMedium."
          EMBED:
            description: An individual user's Share links for use in the EMBED engagementMedium.
            properties:
              EMAIL:
                type: string
                description: "The Share Link for the Email shareMedium."
              FACEBOOK:
                type: string
                description: "The Share Link for the Facebook shareMedium."
              PINTEREST:
                type: string
                description: "The Share Link for the Pinterest shareMedium."
              TWITTER:
                type: string
                description: "The Share Link for the Twitter shareMedium."
              DIRECT:
                type: string
                description: "The Share Link for the Direct shareMedium."
              WHATSAPP:
                type: string
                description: "The Share Link for the Whatsapp shareMedium."
              LINEMESSENGER:
                type: string
                description: "The Share Link for the Line Messenger shareMedium."
              SMS:
                type: string
                description: "The Share Link for the SMS shareMedium."
              FBMESSENGER:
                type: string
                description: "The Share Link for the Facebook Messenger shareMedium."
              UNKNOWN:
                type: string
                description: "The Share Link for an unknown shareMedium."
              LINKEDIN:
                type: string
                description: "The Share Link for the linkedIn shareMedium."
          POPUP:
            description: An individual user's Share links for use in the POPUP engagementMedium.
            properties:
              EMAIL:
                type: string
                description: "The Share Link for the Email shareMedium."
              FACEBOOK:
                type: string
                description: "The Share Link for the Facebook shareMedium."
              PINTEREST:
                type: string
                description: "The Share Link for the Pinterest shareMedium."
              TWITTER:
                type: string
                description: "The Share Link for the Twitter shareMedium."
              DIRECT:
                type: string
                description: "The Share Link for the Direct shareMedium."
              WHATSAPP:
                type: string
                description: "The Share Link for the Whatsapp shareMedium."
              LINEMESSENGER:
                type: string
                description: "The Share Link for the Line Messenger shareMedium."
              SMS:
                type: string
                description: "The Share Link for the SMS shareMedium."
              FBMESSENGER:
                type: string
                description: "The Share Link for the Facebook Messenger shareMedium."
              UNKNOWN:
                type: string
                description: "The Share Link for an unknown shareMedium."
              LINKEDIN:
                type: string
                description: "The Share Link for the linkedIn shareMedium."
          UNKNOWN:
            description: An individual user's Share links for use in an UNKNOWN engagementMedium.
            properties:
              EMAIL:
                type: string
                description: "The Share Link for the Email shareMedium."
              FACEBOOK:
                type: string
                description: "The Share Link for the Facebook shareMedium."
              PINTEREST:
                type: string
                description: "The Share Link for the Pinterest shareMedium."
              TWITTER:
                type: string
                description: "The Share Link for the Twitter shareMedium."
              DIRECT:
                type: string
                description: "The Share Link for the Direct shareMedium."
              WHATSAPP:
                type: string
                description: "The Share Link for the Whatsapp shareMedium."
              LINEMESSENGER:
                type: string
                description: "The Share Link for the Line Messenger shareMedium."
              SMS:
                type: string
                description: "The Share Link for the SMS shareMedium."
              FBMESSENGER:
                type: string
                description: "The Share Link for the Facebook Messenger shareMedium."
              UNKNOWN:
                type: string
                description: "The Share Link for an unknown shareMedium."
              LINKEDIN:
                type: string
                description: "The Share Link for the linkedIn shareMedium."
          HOSTED:
            description: An individual user's Share links for use in the HOSTED engagementMedium.
            properties:
              EMAIL:
                type: string
                description: "The Share Link for the Email shareMedium."
              FACEBOOK:
                type: string
                description: "The Share Link for the Facebook shareMedium."
              PINTEREST:
                type: string
                description: "The Share Link for the Pinterest shareMedium."
              TWITTER:
                type: string
                description: "The Share Link for the Twitter shareMedium."
              DIRECT:
                type: string
                description: "The Share Link for the Direct shareMedium."
              WHATSAPP:
                type: string
                description: "The Share Link for the Whatsapp shareMedium."
              LINEMESSENGER:
                type: string
                description: "The Share Link for the Line Messenger shareMedium."
              SMS:
                type: string
                description: "The Share Link for the SMS shareMedium."
              FBMESSENGER:
                type: string
                description: "The Share Link for the Facebook Messenger shareMedium."
              UNKNOWN:
                type: string
                description: "The Share Link for an unknown shareMedium."
              LINKEDIN:
                type: string
                description: "The Share Link for the linkedIn shareMedium."

    example:
      shareLinks:
        cleanShareLink: "http://ssqt.co/mzbZbgC"
        EMAIL:
          TWITTER: "http://ssqt.co/mGbZbgC"
          UNKNOWN: "http://ssqt.co/mVbZbgC"
          PINTEREST: "http://ssqt.co/RLbZbgC"
          WHATSAPP: "http://ssqt.co/mibZbgC"
          FACEBOOK: "http://ssqt.co/mTbZbgC"
          LINKEDIN: "http://ssqt.co/m1bZbgC"
          DIRECT: "http://ssqt.co/mPbZbgC"
          LINEMESSENGER: "http://ssqt.co/mybZbgC"
          FBMESSENGER: "http://ssqt.co/m4bZbgC"
          SMS: "http://ssqt.co/mObZbgC"
          EMAIL: "http://ssqt.co/mbbZbgC"
        POPUP:
          WHATSAPP: "http://ssqt.co/mFbZbgC"
          TWITTER: "http://ssqt.co/mMbZbgC"
          UNKNOWN: "http://ssqt.co/mBbZbgC"
          PINTEREST: "http://ssqt.co/RzbZbgC"
          FACEBOOK: "http://ssqt.co/m9bZbgC"
          LINKEDIN: "http://ssqt.co/m7bZbgC"
          DIRECT: "http://ssqt.co/m5bZbgC"
          LINEMESSENGER: "http://ssqt.co/mDbZbgC"
          SMS: "http://ssqt.co/mabZbgC"
          FBMESSENGER: "http://ssqt.co/mhbZbgC"
          EMAIL: "http://ssqt.co/mobZbgC"
        MOBILE:
          TWITTER: "http://ssqt.co/mCbZbgC"
          UNKNOWN: "http://ssqt.co/mjbZbgC"
          PINTEREST: "http://ssqt.co/RRbZbgC"
          WHATSAPP: "http://ssqt.co/msbZbgC"
          FACEBOOK: "http://ssqt.co/mnbZbgC"
          LINKEDIN: "http://ssqt.co/m3bZbgC"
          DIRECT: "http://ssqt.co/mebZbgC"
          LINEMESSENGER: "http://ssqt.co/mdbZbgC"
          FBMESSENGER: "http://ssqt.co/mUbZbgC"
          SMS: "http://ssqt.co/mNbZbgC"
          EMAIL: "http://ssqt.co/mEbZbgC"
        HOSTED:
          TWITTER: "http://ssqt.co/mSbZbgC"
          WHATSAPP: "http://ssqt.co/mrbZbgC"
          PINTEREST: "http://ssqt.co/RmbZbgC"
          UNKNOWN: "http://ssqt.co/mAbZbgC"
          FACEBOOK: "http://ssqt.co/mubZbgC"
          LINKEDIN: "http://ssqt.co/mYbZbgC"
          DIRECT: "http://ssqt.co/mtbZbgC"
          LINEMESSENGER: "http://ssqt.co/mWbZbgC"
          SMS: "http://ssqt.co/mqbZbgC"
          FBMESSENGER: "http://ssqt.co/mKbZbgC"
          EMAIL: "http://ssqt.co/mlbZbgC"
        UNKNOWN:
          UNKNOWN: "http://ssqt.co/mzbZbgC"
          TWITTER: "http://ssqt.co/mRbZbgC"
          WHATSAPP: "http://ssqt.co/mIbZbgC"
          PINTEREST: "http://ssqt.co/mpbZbgC"
          FACEBOOK: "http://ssqt.co/mmbZbgC"
          LINKEDIN: "http://ssqt.co/m6bZbgC"
          DIRECT: "http://ssqt.co/mvbZbgC"
          LINEMESSENGER: "http://ssqt.co/m8bZbgC"
          FBMESSENGER: "http://ssqt.co/m0bZbgC"
          SMS: "http://ssqt.co/mkbZbgC"
          EMAIL: "http://ssqt.co/mLbZbgC"
        EMBED:
          WHATSAPP: "http://ssqt.co/mZbZbgC"
          UNKNOWN: "http://ssqt.co/mXbZbgC"
          PINTEREST: "http://ssqt.co/mfbZbgC"
          TWITTER: "http://ssqt.co/mcbZbgC"
          FACEBOOK: "http://ssqt.co/mwbZbgC"
          LINKEDIN: "http://ssqt.co/mHbZbgC"
          DIRECT: "http://ssqt.co/mQbZbgC"
          LINEMESSENGER: "http://ssqt.co/mxbZbgC"
          SMS: "http://ssqt.co/m2bZbgC"
          FBMESSENGER: "http://ssqt.co/mgbZbgC"
          EMAIL: "http://ssqt.co/mJbZbgC"

  WebhookEndpoint:
    description: An endpoint to receive events
    properties:
      endpointUrl:
        type: string
        example: "http://app.example.com/endpoint/sqtch"
        description: The url of the endpoint that receives events
      name:
        type: string
        example: "Zapier"
        description: Optional name of the endpoint that receives events

  VariablesSchema:
    description: The JSON Schema that defines the format of the theme variables. See [theme variables](/themes/variables) for more info.
    type: object
    additionalProperties: true
    example:
      title: Example Theme Variables Schema
      type: object
      properties:
        jsOptions:
          type: object
          properties:
            widget:
              type: object
              properties:
                defaultWidgetType:
                  type: string
                  title: Default Widget Type
                  default: REFERRER_WIDGET
                  enum:
                    - REFERRER_WIDGET
                    - CONVERSION_WIDGET
                  options:
                    enum_titles:
                      - Referrer's Widget
                      - Referred User Widget
            conversionUrls:
              type: array
              items:
                type: string
            widgetUrlMappings:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  showAsCTA:
                    type: boolean
                  displayOnLoad:
                    type: boolean
                  widgetType:
                    type: string
                    enum:
                      - REFERRER_WIDGET
                      - CONVERSION_WIDGET
                    options:
                      enum_titles:
                        - Referrer's Widget
                        - Referred User Widget
        widget:
          type: object
          properties:
            REFERRER_WIDGET:
              type: object
              properties:
                configuration:
                  properties:
                    themeMapping:
                      default: widget
                content:
                  properties:
                    widgetCustomization:
                      allOf:
                        - title: Customize Referral Widget
                          properties:
                            widgetFont:
                              default: '"Helvetica Neue",Helvetica,Arial,sans-serif'
                            headerColor:
                              default: "#4486E1"
                            heading:
                              default:
                                Give ${{math programDetails.referredRewardDetails.credit
                                ' / 100'}} and Get ${{math programDetails.referrerRewardDetails.credit
                                ' / 100'}}!
                            headerDetails:
                              default:
                                Give a friend ${{math programDetails.referredRewardDetails.credit
                                ' / 100'}} credit off {{companyName}} and receive ${{math
                                programDetails.referrerRewardDetails.credit ' / 100'}} for
                                yourself when they pay their first bill.
                            shareCodeDetails:
                              type: string
                              format: markdown
                              title: Call To Action Text
                              default: Share the link below or use the code **{{user.referralCode}}**
                              options:
                                input_height: 100px
                                validate:
                                  - handlebars
                            registrationHeader:
                              type: string
                              format: markdown
                              title: Registration Header
                              default:
                                Thanks for sending your first referral!<br>Give us
                                your email to ensure you get rewarded when your referral is
                                used.
                              options:
                                input_height: 100px
                                validate:
                                  - handlebars
                        - "$ ref": "#/definitions/widget/definitions/content/definitions/generalBody"
                    shareMessaging:
                      allOf:
                        - "$ ref": "#/definitions/widget/definitions/content/definitions/shareContent"
                        - required:
                            - emailShareBody
                            - emailShareSubject
                            - facebookShareSubject
                            - facebookShareBody
                            - twitterShareBody
                            - smsShareBody
                cta:
                  type: object
                  properties:
                    configuration:
                      "$ ref": "#/definitions/widget/definitions/cta/definitions/configuration"
                    content:
                      allOf:
                        - properties:
                            buttonText:
                              default: Refer Friends For Rewards
                        - "$ ref": "#/definitions/widget/definitions/cta/definitions/content"
            CONVERSION_WIDGET:
              type: object
              properties:
                configuration:
                  properties:
                    themeMapping:
                      default: conversion-widget
                content:
                  properties:
                    widgetCustomization:
                      allOf:
                        - title: Customize Referred Widget
                          properties:
                            widgetHeaderImage:
                              type: string
                              format: text
                              minLength: 1
                              title: "Heading Image Url:"
                              default: "{{assets 'images/conversion.png'}}"
                            widgetFont:
                              default: '"Helvetica Neue",Helvetica,Arial,sans-serif'
                            headerColor:
                              default: "#444"
                            heading:
                              default: You were Successfully Referred to {{companyName}}
                            headerDetails:
                              default:
                                Use the Referral Code<br><span id="squatch-share-code">{{referredBy.referredByUser.referralCode}}</span><br>at
                                checkout to receive your referral discount
                            buttonCopy:
                              type: string
                              format: text
                              minLength: 1
                              title: Button Copy
                              default: COPY CODE
                        - "$ ref": "#/definitions/widget/definitions/content/definitions/generalBody"
                cta:
                  type: object
                  properties:
                    configuration:
                      "$ ref": "#/definitions/widget/definitions/cta/definitions/configuration"
                    content:
                      allOf:
                        - properties:
                            buttonText:
                              default: Get Rewarded
                        - "$ ref": "#/definitions/widget/definitions/cta/definitions/content"
        email:
          type: object
          properties:
            REFERRER_REWARD_LIMIT_REACHED:
              type: object
              properties:
                configuration:
                  allOf:
                    - properties:
                        subject:
                          default: You have hit the reward limit!
                        themeMapping:
                          default: emails/referrer-reward-limit
                    - "$ ref": "#/definitions/email/definitions/configuration"
                content:
                  allOf:
                    - properties:
                        headerImageUrl:
                          default: "{{assets 'images/email/reward-limit-header.png'}}"
                        headerContent:
                          default: |-
                            #Reward Limit
                            You have successfully referred the maximum!
                        bodyContent:
                          default:
                            Thanks for spreading the word about {{companyName}}. You've
                            referred so many new people that you've earned the maximum amount
                            of available credit.
                        shareCTA:
                          default:
                            However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}}
                            off with your code. - **{{user.referralCode}}**
                    - "$ ref": "#/definitions/email/definitions/generalContent"
                    - "$ ref": "#/definitions/email/definitions/shareContent"
            REFERRAL_CONVERTED:
              type: object
              properties:
                configuration:
                  allOf:
                    - properties:
                        subject:
                          default:
                            Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit
                            ' / 100'}} of free credit with {{companyName}}
                        themeMapping:
                          default: emails/referral-converted
                    - "$ ref": "#/definitions/email/definitions/configuration"
                content:
                  allOf:
                    - properties:
                        headerImageUrl:
                          default: "{{assets 'images/email/referral-converted-header.png'}}"
                        headerContent:
                          default: |-
                            #Congratulations
                            Your friend has signed up for a {{companyName}} Account!
                        bodyContent:
                          default:
                            You have now earned ${{math programDetails.referrerRewardDetails.credit
                            ' / 100'}} of free credit with {{companyName}}. Refer more friends
                            to save even more!
                    - "$ ref": "#/definitions/email/definitions/generalContent"
                    - "$ ref": "#/definitions/email/definitions/shareContent"
            REFERRAL_STARTED:
              type: object
              properties:
                configuration:
                  allOf:
                    - properties:
                        subject:
                          default:
                            "​{{stringEmptyHandler newReferral.referredUser.firstName
                            onEmpty='A friend'}}​ helped you get one step closer to free credit
                            with {{companyName}}​!"
                        themeMapping:
                          default: emails/referral-started
                    - "$ ref": "#/definitions/email/definitions/configuration"
                content:
                  allOf:
                    - properties:
                        headerImageUrl:
                          default: "{{assets 'images/email/referral-started-header.png'}}"
                        headerContent:
                          default: |-
                            #Good News!
                            Your friend has signed up for a free account with {{companyName}}!
                        bodyContent:
                          default:
                            "{{stringEmptyHandler newReferral.referredUser.firstName
                            onEmpty='A friend'}}​ is currently trying out {{companyName}}.
                            As a thank you from us, if they become a paying user, you will
                            automatically receive ${{math programDetails.referrerRewardDetails.credit
                            ' / 100'}} of free credit with {{companyName}}"
                    - "$ ref": "#/definitions/email/definitions/generalContent"
                    - "$ ref": "#/definitions/email/definitions/shareContent"
      definitions:
        widget:
          definitions:
            content:
              definitions:
                generalBody:
                  type: object
                  properties:
                    widgetFont:
                      type: string
                      title: "Widget Font:"
                      enum:
                        - '"Helvetica Neue",Helvetica,Arial,sans-serif'
                        - "'Lato',sans-serif"
                        - "'Times New Roman'"
                        - Arial
                        - Courier
                        - Tahoma
                        - Verdana
                        - Georgia
                      options:
                        enum_titles:
                          - Helvetica Neue
                          - Lato
                          - Times New Roman
                          - Arial
                          - Courier
                          - Tahoma
                          - Verdana
                          - Georgia
                    headerColor:
                      type: string
                      format: text
                      minLength: 1
                      title: "Heading Text Color (hex code):"
                      options:
                        validate:
                          - hex-color
                    heading:
                      type: string
                      minLength: 1
                      format: markdown
                      title: "Heading Text:"
                      options:
                        input_height: 100px
                        validate:
                          - handlebars
                    headerDetails:
                      type: string
                      minLength: 1
                      format: markdown
                      title: "Body Text:"
                      options:
                        input_height: 100px
                        validate:
                          - handlebars
                shareContent:
                  title: Share Messaging
                  type: object
                  properties:
                    emailShareSubject:
                      type: string
                      description: Email share subject
                      minLength: 4
                      default:
                        Get ${{math programDetails.referredRewardDetails.credit '
                        / 100'}} off {{companyName}}
                    emailShareBody:
                      type: string
                      description: Email share body
                      minLength: 4
                      default:
                        Sign up for a {{companyName}} account and we both get ${{math
                        programDetails.referredRewardDetails.credit ' / 100'}} free credit.
                        Use this link {{shareLinks.emailShareLink}}
                    facebookShareImageURL:
                      type: string
                      description: Facebook URL Image
                      default: ""
                    facebookShareSubject:
                      type: string
                      description: Facebook share subject
                      minLength: 4
                      default:
                        Get ${{math programDetails.referredRewardDetails.credit '
                        / 100'}} off {{companyName}}
                    facebookShareBody:
                      type: string
                      description: Facebook share subject
                      minLength: 4
                      default:
                        Sign up for a {{companyName}} account and we both get ${{math
                        programDetails.referredRewardDetails.credit ' / 100'}} free credit.
                        Use this link {{shareLinks.facebookShareLink}}
                    twitterShareBody:
                      type: string
                      description: Twitter share body
                      minLength: 4
                      default:
                        Sign up for a {{companyName}} account and we both get ${{math
                        programDetails.referredRewardDetails.credit ' / 100'}} free credit.
                        Use this link {{shareLinks.twitterShareLink}}
                    smsShareBody:
                      type: string
                      description: SMS share body
                      minLength: 4
                      default:
                        Sign up for a {{companyName}} account and we both get ${{math
                        programDetails.referredRewardDetails.credit ' / 100'}} free credit.
                        Use this link {{share-link 'SMS'}}
            cta:
              definitions:
                configuration:
                  type: object
                  properties:
                    themeMapping:
                      default: cta-widget
                content:
                  type: object
                  title: Customize CTA Button
                  properties:
                    buttonSide:
                      type: string
                      title: "Button Side:"
                      default: right
                      enum:
                        - left
                        - right
                        - center
                      options:
                        enum_titles:
                          - Left Side
                          - Right Side
                          - Center
                    buttonPosition:
                      type: string
                      title: "Button Position:"
                      default: bottom
                      enum:
                        - top
                        - bottom
                        - middle
                      options:
                        enum_titles:
                          - Top
                          - Bottom
                          - Middle
                    buttonColor:
                      type: string
                      format: text
                      minLength: 1
                      title: "Button Color (hex code):"
                      default: "#4486E1"
                      options:
                        validate:
                          - hex-color
                    buttonText:
                      type: string
                      title: Button Text
                      format: markdown
                      propertyOrder: 4
                      options:
                        validate:
                          - handlebars
                        input_height: 50px
                    buttonWidth:
                      type: integer
                      title: Button Width
                      format: number
                      default: 230
        email:
          definitions:
            configuration:
              type: object
              title: Email Defaults
              properties:
                fromName:
                  type: string
                  title: From Name
                  default: "{{companyName}}"
                  propertyOrder: 1
                  minLength: 1
                  options:
                    validate:
                      - handlebars
                fromAddress:
                  type: string
                  title: From Address
                  format: email
                  default: referral@mail.saasquat.ch
                  propertyOrder: 2
                  minLength: 5
                  options:
                    validate:
                      - email
                subject:
                  type: string
                  title: Subject
                  format: textarea
                  default: Referral Update
                  propertyOrder: 3
                  minLength: 1
                  options:
                    validate:
                      - handlebars
                    input_height: 50px
                themeMapping:
                  options:
                    hidden: true
            generalContent:
              type: object
              properties:
                headerImageUrl:
                  type: string
                  title: Header Image URL
                  propertyOrder: 1
                  options:
                    validate:
                      - handlebars
                headerContent:
                  type: string
                  title: Header Content
                  format: markdown
                  propertyOrder: 2
                  options:
                    validate:
                      - handlebars
                    input_height: 50px
                bodyContent:
                  type: string
                  title: Body Content
                  format: markdown
                  propertyOrder: 3
                  options:
                    validate:
                      - handlebars
                    input_height: 50px
                footer:
                  type: string
                  title: Footer
                  format: markdown
                  propertyOrder: 1001
                  options:
                    validate:
                      - handlebars
                    input_height: 50px
            shareContent:
              type: object
              properties:
                shareCTA:
                  type: string
                  title: Share Code CTA
                  format: markdown
                  propertyOrder: 4
                  default: Keep sharing your code and earn more discounts - **{{user.referralCode}}**
                  options:
                    validate:
                      - handlebars
                    input_height: 50px
                hasShareLink:
                  type: boolean
                  format: checkbox
                  title: Enable Share Link
                  propertyOrder: 5
                  default: true
                shareButtonHeader:
                  type: string
                  title: Share Button Header
                  format: markdown
                  propertyOrder: 6
                  default:
                    Refer and Earn ${{math programDetails.referrerRewardDetails.credit
                    ' / 100'}} of Credit
                  options:
                    validate:
                      - handlebars
                    input_height: 50px
      required:
        - jsOptions
        - widget
        - email

  VariablesInstance:
    description: The stored values for the variables.  See [theme variables](/themes/variables) for more info.
    type: object
    additionalProperties: true
    example:
      jsOptions:
        widget:
          defaultWidgetType: REFERRER_WIDGET
        conversionUrls:
          - "^https:\\/\\/example\\.com\\/thank\\-you([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
        widgetUrlMappings:
          - widgetType: CONVERSION_WIDGET
            showAsCTA: true
            displayOnLoad: true
            url: "^https:\\/\\/example\\.com\\/widgetPage\\/([^a-zA-Z0-9.\\-_~!$&'()*+,;=:@/]+?.*$|$)"
      widget:
        REFERRER_WIDGET:
          configuration:
            themeMapping: widget
          content:
            widgetCustomization:
              widgetFont: '"Helvetica Neue",Helvetica,Arial,sans-serif'
              headerColor: "#4486E1"
              heading:
                Give ${{math programDetails.referredRewardDetails.credit ' / 100'}}
                and Get ${{math programDetails.referrerRewardDetails.credit ' / 100'}}!
              headerDetails:
                Give a friend ${{math programDetails.referredRewardDetails.credit
                ' / 100'}} credit off {{companyName}} and receive ${{math programDetails.referrerRewardDetails.credit
                ' / 100'}} for yourself when they pay their first bill.
              shareCodeDetails: Share the link below or use the code **{{user.referralCode}}**
              registrationHeader:
                Thanks for sending your first referral!<br>Give us your
                email to ensure you get rewarded when your referral is used.
            shareMessaging:
              emailShareSubject:
                Get ${{math programDetails.referredRewardDetails.credit
                ' / 100'}} off {{companyName}}
              emailShareBody:
                Sign up for a {{companyName}} account and we both get ${{math
                programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use
                this link {{shareLinks.emailShareLink}}
              facebookShareImageURL: ""
              facebookShareSubject: Facebook Title in SaaSquatch Portal
              facebookShareBody: Facebook Share body in SaaSquatch Portal
              twitterShareBody:
                Sign up for a {{companyName}} account and we both get ${{math
                programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use
                this link {{shareLinks.twitterShareLink}}
              smsShareBody:
                Sign up for a {{companyName}} account and we both get ${{math
                programDetails.referredRewardDetails.credit ' / 100'}} free credit. Use
                this link {{share-link 'SMS'}}
          cta:
            configuration:
              themeMapping: cta-widget
            content:
              buttonSide: right
              buttonPosition: bottom
              buttonColor: "#4486E1"
              buttonWidth: 230
              buttonText: Refer Friends For Rewards
        CONVERSION_WIDGET:
          configuration:
            themeMapping: conversion-widget
          content:
            widgetCustomization:
              widgetHeaderImage: "{{assets 'images/conversion.png'}}"
              widgetFont: '"Helvetica Neue",Helvetica,Arial,sans-serif'
              headerColor: "#444"
              heading: You were Successfully Referred to {{companyName}}
              headerDetails:
                Use the Referral Code<br><span id="squatch-share-code">{{referredBy.referredByUser.referralCode}}</span><br>at
                checkout to receive your referral discount
              buttonCopy: COPY CODE
          cta:
            configuration:
              themeMapping: cta-widget
            content:
              buttonSide: right
              buttonPosition: bottom
              buttonColor: "#4486E1"
              buttonWidth: 230
              buttonText: Refer Friends For Rewards
      email:
        REFERRER_REWARD_LIMIT_REACHED:
          configuration:
            fromName: "{{companyName}}"
            fromAddress: referral@mail.saasquat.ch
            subject: You have hit the reward limit!
            themeMapping: emails/referrer-reward-limit
          content:
            shareCTA:
              However, you can keep referring new users and giving ${{programDetails.referrerRewardDetails.credit}}
              off with your code. - **{{user.referralCode}}**
            hasShareLink: true
            shareButtonHeader:
              Refer and Earn ${{math programDetails.referrerRewardDetails.credit
              ' / 100'}} of Credit
            headerImageUrl: "{{assets 'images/email/reward-limit-header.png'}}"
            headerContent: |-
              #Reward Limit
              You have successfully referred the maximum!
            bodyContent:
              Thanks for spreading the word about {{companyName}}. You've referred
              so many new people that you've earned the maximum amount of available credit.
        REFERRAL_CONVERTED:
          configuration:
            fromName: "{{companyName}}"
            fromAddress: referral@mail.saasquat.ch
            subject:
              Congrats! You have earned ${{math programDetails.referrerRewardDetails.credit
              ' / 100'}} of free credit with {{companyName}}
            themeMapping: emails/referral-converted
          content:
            shareCTA: Keep sharing your code and earn more discounts - **{{user.referralCode}}**
            hasShareLink: true
            shareButtonHeader:
              Refer and Earn ${{math programDetails.referrerRewardDetails.credit
              ' / 100'}} of Credit
            headerImageUrl: "{{assets 'images/email/referral-converted-header.png'}}"
            headerContent: |-
              #Congratulations
              Your friend has signed up for a {{companyName}} Account!
            bodyContent:
              You have now earned ${{math programDetails.referrerRewardDetails.credit
              ' / 100'}} of free credit with {{companyName}}. Refer more friends to save
              even more!
        REFERRAL_STARTED:
          configuration:
            fromName: "{{companyName}}"
            fromAddress: referral@mail.saasquat.ch
            subject:
              "​{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A
              friend'}}​ helped you get one step closer to free credit with {{companyName}}​!"
            themeMapping: emails/referral-started
          content:
            shareCTA: Keep sharing your code and earn more discounts - **{{user.referralCode}}**
            hasShareLink: true
            shareButtonHeader:
              Refer and Earn ${{math programDetails.referrerRewardDetails.credit
              ' / 100'}} of Credit
            headerImageUrl: "{{assets 'images/email/referral-started-header.png'}}"
            headerContent: |-
              #Good News!
              Your friend has signed up for a free account with {{companyName}}!
            bodyContent:
              "{{stringEmptyHandler newReferral.referredUser.firstName onEmpty='A
              friend'}}​ is currently trying out {{companyName}}. As a thank you from us,
              if they become a paying user, you will automatically receive ${{math programDetails.referrerRewardDetails.credit
              ' / 100'}} of free credit with {{companyName}}"

  ThemeContext:
    description: The context object provided to themes for rendering the current user's widget.
    properties:
      tenantAlias:
        type: string
        example: abdsds5124abewet
        description: The active tenant's alias
      companyName:
        type: string
        example: Acme Corp
        description: The name of the company for the referral program
      programDetails:
        type: object
        description: The details of the incentives used for the referral program.
        properties:
          referredRewardDetails:
            $ref: "#/definitions/RewardTemplate"
          referrerRewardDetails:
            $ref: "#/definitions/RewardTemplate"
      user:
        $ref: "#/definitions/User"
      referrals:
        type: array
        description: The referrals made by the active user
        items:
          $ref: "#/definitions/ThemeReferrerReferralDto"
      referralsLength:
        type: integer
        description: The total number of referrals made by this user
      rewardBalances:
        type: array
        description: An array of reward balances for this user
        items:
          $ref: "#/definitions/RewardBalance"
      shareLinks:
        $ref: "#/definitions/Sharelink"
      referredBy:
        $ref: "#/definitions/ThemeReferredReferralDto"
      variables:
        $ref: "#/definitions/VariablesInstance"
      variablesSchema:
        $ref: "#/definitions/VariablesSchema"
      mode:
        type: string
        description: The mode the widget has been loaded in
        enum:
          - POPUP
          - EMBED
          - NOCONTENT
      assetVersion:
        type: string
        description: A unique hash used to version assets.
      headerVersion:
        type: string
        description: A unique version number used internally.
      newReferral:
        description: Details of a user who was referred by the current user (Available only in `REFERRAL_STARTED` email context)
      convertedReferral:
        description: Details of a user who was referred by the current user (Available only in `REFERRAL_CONVERTED` email context)
      locale:
        type: string
        description: |
          The user locale, used for [Internationalization](/themes/internationalization).
          The locale must be of the format `language_COUNTRY` where the language code must be lowercase and the country code must be uppercase.
          The separator must be an underscore.
          Examples `en` or `en_US` or `zh_CN`
  OpenUser:
    description: An object describing an individual user returned by an open endpoint
    required:
      - id
      - accountId
      - firstName
    properties:
      id:
        type: string
        example: "219065"
        description: The unique identifier for this user.
      cookieId:
        type: string
        example: "2523423436323"
        description: A unique identifier for this participant.
      accountId:
        type: string
        example: "accc9065"
        description: The unique identifier of the Account that this user belongs to.
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      referralCodes:
        type: object
        items:
          type: string
        example:
          classic: "BOBTESTERSON"
          fakeProgram1: "BOBTESTERSON123"
        description: The primary referral codes across all programs that the user currently has.
      imageUrl:
        type: string
        example: "https://www.example.com/profile/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      locale:
        type: string
        example: "en_US"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
      countryCode:
        type: string
        example: "US"
        description: The user's ISO 3166-1 Alpha-2 country code. For example, "CA" for Canada and "ES" for Spain.
      dateUsTaxFormSubmitted:
        type: integer
        example: 1619647338270
        description: The timestamp of when a users W-9 tax form was submitted. Used for [W-9 Compliance](/features/w-9-compliance).
      referredBy:
        type: object
        description: An object containing information about who referred this user.
        properties:
          code:
            type: string
            example: "JONDOE1234"
            description: The referral code of the person that referred this account.
          isConverted:
            type: boolean
            example: true
            description: Whether or not this referred user has hit to goal post and the referral should be converted to kick of reward creation for the referrer.
          newlyReferred:
            type: boolean
            example: true
            description: Whether or not this referred user was referred recently.
      referredByCodes:
        type: array
        items:
          type: string
        description: An array of referral codes used to refer this account.
      referable:
        type: boolean
        example: true
        description: Flag used by the SaaSquatch system to determine whether a user is able to be referred.
      customFields:
        type: object
        description: |
          An object containing the custom fields for this user.

          Learn more about the available custom field functionality in our [Custom Fields Developer Guide](/features/custom-user-fields)
      segments:
        type: array
        items:
          type: string
        description: A list of segments that a user is a member of.
      shareLinks:
        readOnly: true
        $ref: "#/definitions/Sharelink"
      programShareLinks:
        type: object
        items:
          type: object
        description: The primary share links available for a users programs.
        $ref: "#/definitions/ProgramShareLink"

    example:
      id: "898746321"
      cookieId: "2523423436323"
      accountId: "accc9065"
      firstName: "Bob"
      lastName: "Testerson"
      email: "bob@example.com"
      referable: true
      locale: null
      countryCode: "US"
      dateUsTaxFormSubmitted: 1619647338270
      referralCode: "BOBTESTERSON"
      referralCodes:
        classic: "BOBTESTERSON"
        fakeProgram1: "FREE"
      referredBy:
        code: "JONDOE1234"
        isConverted: true
        newlyReferred: false
      referredByCodes:
        - "JONDOE1234"
      imageUrl: ""
      customFields:
        lastPurchaseDate: 1512152525513
        plan: "Pro+"
        phone: 19055551234
        address: "123 Main st., City, Province, Country, H0H0H0"
        shoeSize: 12.5
        currency: "CAD"
      segments: ["segment1", "segment3"]
      shareLinks:
        $ref: "#/definitions/Sharelink/example"
      programShareLinks:
        $ref: "#/definitions/ProgramShareLink/example"

  UserByCode:
    title: Subset of user information
    description: A subset of user information that is publicly visible via someone's referral code.
    properties:
      id:
        type: string
        example: "219065"
        description: The unique identifier provided for this user.
      accountId:
        type: string
        example: "accc9065"
        description: The unique identifier of the Account that this user belongs to.
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastInitial:
        type: string
        description: The first initial of the user's last name
      referralCode:
        type: string
        description: The referral code used to look up this user
      imageUrl:
        type: string
        example: "https://www.example.com/profile/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.

  OpenUserStub:
    title: A Open User object stub
    description: An object describing an individual user submitted to an open endpoint when you want to create a new user, called a OpenUserStub.
    required:
      - id
      - accountId
    properties:
      id:
        type: string
        example: "219065"
        description: The unique identifier provided for this user.
      accountId:
        type: string
        example: "accc9065"
        description: The unique identifier of the Account that this user belongs to.
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      referable:
        type: boolean
        example: true
        description: Flag used by the SaaSquatch system to determine whether a user is able to be referred.
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      referralCodes:
        type: object
        items:
          type: string
        example:
          classic: "BOBTESTERSON"
          fakeProgram1: "FREE"
        description: The primary custom referral codes for different programs.
      paymentProviderId:
        type: string
        example: "cus_8rVOAthabctvT6"
        description: The paymentProviderId is either the Stripe Customer ID, the Recurly Account ID, the Braintree Account ID or the Zuora Account ID. This field cannot be updated. Do not include this arguement on an API-only program, or unless looking to set it.
      locale:
        type: string
        example: "en_US"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
      countryCode:
        type: string
        example: "US"
        description: The user's ISO 3166-1 Alpha-2 country code. For example, "CA" for Canada and "ES" for Spain.
      dateUsTaxFormSubmitted:
        type: integer
        example: 1619647338270
        description: The timestamp of when a users W-9 tax form was submitted. Used for [W-9 Compliance](/features/w-9-compliance).
      referredBy:
        type: object
        description: An object containing information about who referred this user.
        properties:
          code:
            type: string
            example: "JONDOE1234"
            description: The referral code of the person that referred this account.
          isConverted:
            type: boolean
            example: true
            description: Whether or not this referred user has hit to goal post and the referral should be converted to kick of reward creation for the referrer.
      referredByCodes:
        type: array
        items:
          type: string
        description: An array of referral codes used to refer this account.
        example:
          - "JONDOE1234"
          - "JOHNDOECODE"
      cookies:
        type: string
        example: eyJhcHAucmVmZXJyYWxzYWFzcXVhdGNoLmNvbSI6eyJ0ZW5hbnRBbGlhc19DT0RFIjp7ImNvZGVzIjp7InByb2dyYW0xIjoiQ09ERTEifSwiY29kZXNFeHAiOnsiQ09ERTEiOjEyMzQ1Njd9fX19
        description: |
          The Base64URL encoded attribution cookie values. When decoded, the schema will resemble the following:

          {"app.referralsaasquatch.com": {"tenantAlias_CODE": {"codes": {"program1": "CODE1"},"codesExp": {"CODE1": 1234567}}}}
      imageUrl:
        type: string
        example: "https://www.example.com/profile/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      segments:
        type: array
        items:
          type: string
        description: |
          A list of operations for adding and removing a user from segments.

          Details about the supported operators and operations for adding and removing users from a segment can be found in our [User Segmentation](/features/user-segmentation/#saasquatch-api-and-squatchjs-segmentation) article.
        example: ["segment1", "~segment2"]
      shareLinks:
        type: object
        items:
          type: string
        example:
          fakeProgram1: "http://example.com/free"
        description: The primary custom shareLinks for different programs. If a given program does not have a referral code, one will be generated.
      customFields:
        type: object
        description: |
          An object containing the custom fields for this user.

          Learn more about the available custom field functionality in our [Custom Fields Developer Guide](/features/custom-user-fields)
        example:
          lastPurchaseDate: 1512152525513
          plan: "Pro+"
          phone: 19055551234
          address: "123 Main st., City, Province, Country, H0H0H0"
          shoeSize: 12.5
          currency: "CAD"

  OpenCookieUserStub:
    title: A Open Cookie User object stub
    description: An object describing an individual user submitted to an open endpoint when you want to create a new cookie user, called a OpenCookieUserStub.
    properties:
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      referralCodes:
        type: object
        items:
          type: string
        example:
          classic: "BOBTESTERSON"
          fakeProgram1: "BOBTESTERSON123"
        description: The primary custom referral codes for different programs.
      locale:
        type: string
        example: "en_US"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
      paymentProviderId:
        type: string
        example: "cus_dk3hj3k3sfj8987"
        description: |
          The user's Stripe Customer ID, the Recurly Account ID, the Braintree Account ID, or the Zuora Account ID. This value is not updatable and can only be set once. This field can be left out if not explicitly setting the value.
      referredBy:
        type: object
        description: An object containing information about who referred this user.
        properties:
          code:
            type: string
            example: "JONDOE1234"
            description: The referral code of the person that referred this account.
          isConverted:
            type: boolean
            example: true
            description: Whether or not this referred user has hit to goal post and the referral should be converted to kick of reward creation for the referrer.
      referredByCodes:
        type: array
        items:
          type: string
        description: An array of referral codes used to refer this account.
        example:
          - "JONDOE1234"
          - "JOHNDOECODE"
      imageUrl:
        type: string
        example: "https://www.example.com/profile/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      customFields:
        type: object
        description: |
          An object containing the custom fields for this user.

          Learn more about the available custom field functionality in our [Custom Fields Developer Guide](/features/custom-user-fields)
        example:
          lastPurchaseDate: 1512152525513
          plan: "Pro+"
          phone: 19055551234
          address: "123 Main st., City, Province, Country, H0H0H0"
          shoeSize: 12.5
          currency: "CAD"

  OpenCookieUser:
    description: An object describing an individual user returned by an open endpoint
    properties:
      firstName:
        type: string
        example: "Bob"
        description: |
          The user's first name
      lastName:
        type: string
        example: "Testerson"
        description: |
          The user's last name
      email:
        type: string
        example: "bob@example.com"
        description: The email address provided for the user. SaaSquatch uses this to notify someone when they have a successful referral.
      referralCode:
        type: string
        example: "BOBTESTERSON"
        description: The referral code *used for sharing by this user*
      referralCodes:
        type: object
        items:
          type: string
        example:
          classic: "BOBTESTERSON"
          fakeProgram1: "BOBTESTERSON123"
        description: The primary custom referral codes for different programs.
      locale:
        type: string
        example: "en_US"
        description: |
          The user's locale, used for [Internationalization](/themes/internationalization). The locale must be of the format 'language_COUNTRY' where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.
      paymentProviderId:
        type: string
        example: "cus_dk3hj3k3sfj8987"
        description: |
          The user's Stripe Customer ID, the Recurly Account ID, the Braintree Account ID, or the Zuora Account ID. This value is not updatable and can only be set once. This field can be left out if not explicitly setting the value.
      referredBy:
        type: object
        description: An object containing information about who referred this user.
        properties:
          code:
            type: string
            example: "JONDOE1234"
            description: The referral code of the person that referred this account.
          isConverted:
            type: boolean
            example: true
            description: Whether or not this referred user has hit to goal post and the referral should be converted to kick of reward creation for the referrer.
      referredByCodes:
        type: array
        items:
          type: string
        description: An array of referral codes used to refer this account.
        example:
          - "JONDOE1234"
          - "JOHNDOECODE"
      imageUrl:
        type: string
        example: "https://www.example.com/profile/ab5111251125"
        description: |
          Optionally used in widgets, emails, and themes. If you provide a absolute profile image URL the minimum image size is 80px x 80px.
      shareLinks:
        readOnly: true
        $ref: "#/definitions/Sharelink"
      programShareLinks:
        type: object
        items:
          type: object
        description: The primary share links available for a users programs.
        $ref: "#/definitions/GeneratedProgramShareLink"
      customFields:
        type: object
        description: |
          An object containing the custom fields for this user.

          Learn more about the available custom field functionality in our [Custom Fields Developer Guide](/features/custom-user-fields)
        example:
          lastPurchaseDate: 1512152525513
          plan: "Pro+"
          phone: 19055551234
          address: "123 Main st., City, Province, Country, H0H0H0"
          shoeSize: 12.5
          currency: "CAD"
    example:
      id: "898746321"
      cookieId: "2523423436323"
      accountId: "accc9065"
      firstName: "Bob"
      lastName: "Testerson"
      email: "bob@example.com"
      referable: true
      locale: null
      referralCode: "BOBTESTERSON"
      referralCodes:
        classic: "BOBTESTERSON"
        fakeProgram1: "BOBTESTERSON123"
      referredBy:
        code: "JONDOE1234"
        isConverted: true
        newlyReferred: false
      referredByCodes:
        - "JONDOE1234"
      imageUrl: ""
      customFields:
        lastPurchaseDate: 1512152525513
        plan: "Pro+"
        phone: 19055551234
        address: "123 Main st., City, Province, Country, H0H0H0"
        shoeSize: 12.5
        currency: "CAD"
      segments: ["segment1", "segment3"]
      shareLinks:
        $ref: "#/definitions/Sharelink/example"
      programShareLinks:
        $ref: "#/definitions/GeneratedProgramShareLink/example"

  ListEnvelope:
    description: A generic base model to help with paginating lists. The `count` counts the number in this list, and `totalCount` gives the total available results.
    properties:
      count:
        type: integer
        description: The number of results returned in this list, see `totalCount` for all rows.
      totalCount:
        type: integer
        description: The total number of results available overall, see `count` for the number of rows in this list.

  #
  # ========== Response / Envelope Types ==============
  #
  # Only REST response envelopers included in this section.
  #

  UserList:
    type: object
    description: A list of User objects as `users`, with the fields `count` and `totalCount` to help with pagination.
    properties:
      count:
        type: integer
        description: The number of results returned in this list, see `totalCount` for all rows.
      totalCount:
        type: integer
        description: The total number of results available overall, see `count` for the number of rows in this list.
      users:
        type: array
        description: A list of User objects. This is the actual data in this list envelope.
        items:
          $ref: "#/definitions/User"

  ReferralList:
    type: object
    description: A list of Referral objects as `referrals`, with the fields `count` and `totalCount` to help with pagination.
    properties:
      count:
        type: integer
        description: The number of results returned in this list, see `totalCount` for all rows.
      totalCount:
        type: integer
        description: The total number of results available overall, see `count` for the number of rows in this list.
      referrals:
        type: array
        description: A list of Referral objects. This is the actual data in this list envelope.
        items:
          $ref: "#/definitions/Referral"

  PIIReferralList:
    type: object
    description: A list of Referral objects as `referrals`, with the fields `count` and `totalCount` to help with pagination.
    properties:
      referrals:
        type: array
        description: A list of Referral objects. This is the actual data in this list envelope.
        items:
          $ref: "#/definitions/PIIReferral"
      count:
        type: integer
        description: The number of results returned in this list, see `totalCount` for all rows.
      totalCount:
        type: integer
        description: The total number of results available overall, see `count` for the number of rows in this list.

  RewardDebitResponse:
    description: Details about a successful Reward Balance Debit transaction.
    properties:
      creditRedeemed:
        type: integer
        example: 200
        description: The amount of credit that was just debitted.
      creditAvailable:
        type: integer
        example: 1800
        description: The remaining credit in this account of the same unit type.
      unit:
        type: string
        example: cents
        description: The type of credit that was just debitted.

  ExportList:
    description: A list of Export objects with additional data for pagination.
    properties:
      data:
        type: array
        description: A list of Export objects. This is the actual data in this list envelope.
        items:
          $ref: "#/definitions/Export"
      count:
        type: integer
        description: The number of results returned in this list, see `totalCount` for all rows.
        example: 10
      totalCount:
        type: integer
        description: The total number of results available overall, see `count` for the number of rows in this list.
        example: 2415

  ExportStub:
    description: An Export lets you get your customer data out of your Referral SaaSquatch tenant. There are exports for returning Users, Referrals and Reward Balances.
    required:
      - type
    properties:
      type:
        description: The type of Export that's being requested.
        type: string
        enum:
          - USER
          - USER_REFERRAL
          - REFERRAL
          - USER_REWARD_BALANCE
          - REWARD_BALANCE
          - REWARD
        example: REFERRAL
      format:
        description: The format of the Export
        type: string
        default: CSV
        example: CSV
        enum:
          - CSV
          - XLSX
      name:
        description: A user-friendly name for this report. Useful for keeping track of which report is which.
        type: string
      requester:
        description: Detail on the service or user that requested this report.
        type: string
        example: "Referral SaaSquatch for Salesforce"

      params:
        description: >
          Filter parameters for limiting the types of results returned. When parameters are included, their are grouped by a logical "AND" so
          it's possible to create situations that return no results.
        type: object
        properties:
          createdSince:
            description: >
              Filters for results that have been **created since this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.
            type: integer
            format: int64
          createdBefore:
            description: >
              Filters for results that have been **created before this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.
            type: integer
            format: int64
          updatedSince:
            description: >
              Filters for results that have been **updated since this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
          updatedBefore:
            description: >
              Filters for results that have been **updated before this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
          createdOrUpdatedSince:
            description: >
              Filters for results that have been **created or updated since this date**.
              Useful for doing incremental exports into a data warehouse.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
            example: 1471486152087
          createdOrUpdatedBefore:
            description: >
              Filters for results that have been **created or updated before this date**.
              Useful for doing incremental exports into a data warehouse.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
            example: 1471486452087
          programId:
            description: >
              The ID of the program that each user's sharelinks and referral code should be populated from.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: string
            example: my-program-id
          filter:
            description: >
              A filter that defines the rewards to be exported. See GraphQL RewardFilterInput.
              Works with reports of type `REWARD`.
            type: object
          at:
            description: >
              An optional timestamp for exporting the rewards' states at a specific point in time.
              Works with reports of type `REWARD`.
            type: integer
            format: int64
            example: 1471486452087
          fields:
            description: Settings related to the fields included in the exports
            type: object
            properties:
              includeUserStatsFields:
                description: Whether user stats fields should be included. Works with reports of type `USER`.
                type: boolean
                default: false
              includeUserFields:
                description: Whether user fields should be included. Works with reports of type `REWARD`.
                type: boolean
                default: false
              includeReferralFields:
                description: Whether referrals fields should be included. Works with reports of type `REWARD`.
                type: boolean
                default: false

  Export:
    description: An Export lets you get your customer data out of your Referral SaaSquatch tenant. There are exports for returning Users, Referrals and Reward Balances.
    required:
      - type
    properties:
      type:
        description: The type of Export that's being requested.
        type: string
        enum:
          - USER
          - USER_REFERRAL
          - REFERRAL
          - USER_REWARD_BALANCE
          - REWARD_BALANCE
          - REWARD
        example: REFERRAL
      format:
        description: The format of the Export
        type: string
        default: CSV
        example: CSV
        enum:
          - CSV
          - XLSX
      name:
        description: A user-friendly name for this report. Useful for keeping track of which report is which.
        type: string
      requester:
        description: Detail on the service or user that requested this report.
        type: string
        example: "Referral SaaSquatch for Salesforce"

      params:
        description: >
          Filter parameters for limiting the types of results returned. When parameters are included, their are grouped by a logical "AND" so
          it's possible to create situations that return no results.
        type: object
        properties:
          createdSince:
            description: >
              Filters for results that have been **created since this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.
            type: integer
            format: int64
          createdBefore:
            description: >
              Filters for results that have been **created before this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`, `USER_REWARD_BALANCE`, `REWARD_BALANCE`.
            type: integer
            format: int64
          updatedSince:
            description: >
              Filters for results that have been **updated since this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
          updatedBefore:
            description: >
              Filters for results that have been **updated before this date**.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
          createdOrUpdatedSince:
            description: >
              Filters for results that have been **created or updated since this date**.
              Useful for doing incremental exports into a data warehouse.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
            example: 1471486152087
          createdOrUpdatedBefore:
            description: >
              Filters for results that have been **created or updated before this date**.
              Useful for doing incremental exports into a data warehouse.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: integer
            format: int64
            example: 1471486452087
          programId:
            description: >
              The ID of the program that each user's sharelinks and referral code should be populated from.
              Works with reports of type `USER`, `USER_REFERRAL`, `REFERRAL`.
            type: string
            example: my-program-id
          filter:
            description: >
              A filter that defines the rewards to be exported. See GraphQL RewardFilterInput.
              Works with reports of type `REWARD`.
            type: object
          at:
            description: >
              An optional timestamp for exporting the rewards' states at a specific point in time.
              Works with reports of type `REWARD`.
            type: integer
            format: int64
            example: 1471486452087
          fields:
            description: Settings related to the fields included in the exports
            type: object
            properties:
              includeUserStatsFields:
                description: Whether user stats fields should be included. Works with reports of type `USER`.
                type: boolean
                default: false
              includeUserFields:
                description: Whether user fields should be included. Works with reports of type `REWARD`.
                type: boolean
                default: false
              includeReferralFields:
                description: Whether referrals fields should be included. Works with reports of type `REWARD`.
                type: boolean
                default: false

      ### -- Read-only fields below here -- ###
      id:
        description: A unique ID used to keep track of an export's life. Can be used to lookup an exports status.
        type: string
        readOnly: true
        example: 57b519f4e4b057c1b63925df
      status:
        description: The status of this export. `PENDING` while queued or running, `COMPLETED` when done, and `ABORTED` if there are unrecoverable errors.
        type: string
        readOnly: true
        example: PENDING
        enum:
          - PENDING
          - COMPLETED
          - ABORTED
          - EXPIRED
      dateCreated:
        description: The timestamp when this request was created. This field will never change.
        type: integer
        format: int64
        readOnly: true
        example: 1471486452362
      dateCompleted:
        description: The timestamp when this report finished processing and had it's `status` set to `COMPLETED`.
        type: integer
        format: int64
        readOnly: true
        example: 1474510479612
      dateExpires:
        description: The timestamp when this report will expire. By default all reports will eventually expire.
        type: integer
        format: int64
        readOnly: true
        example: 1471486479612

  # ========== Request Types ==============
  #
  # Only REST request objects included in this section.
  #
  AccountDiscountRequest:
    required:
      - accountId
      - paymentProviderId
      - couponCode
    properties:
      accountId:
        type: string
        example: abc123
        description: |
          Unique identifier for the account. We use this ID to link a group of users together. See [Shared vs Solo Accounts](/shared-vs-solo-accounts/) to see what you should use here.
      paymentProviderId:
        type: string
        example: cus_123
        description: |
          The payment provider ID of the newly created account from Braintree or Zuora. This will be the Braintree Account ID or the Zuora Account ID of the newly created account.
      couponCode:
        type: string
        example: BOBTESTERSON
        description: |
          The coupon/referral code of the user that referred this user. Can be obtained from the referral-tracking cookie using squatch.js coupon autofill.
  RewardDebitRequest:
    description: A request to debit a single reward
    required:
      - amount
      - unit
    properties:
      amount:
        type: integer
        example: 200
        description: The amount of credit to be debitted.
      unit:
        type: string
        example: cents
        description: |
          The type of credit to be debitted. E.g. "free-months" or "cents"
  RewardBalanceDebitRequest:
    description: A request to debit a Reward Balance
    required:
      - accountId
      - unit
      - amount
    properties:
      accountId:
        type: string
        description: The ID of the account to be debitted.
        example: abc123
      unit:
        type: string
        example: cents
        description: |
          The type of credit to be debitted. E.g. "free-months" or "cents"
      amount:
        type: integer
        example: 200
        description: The amount of credit to be debitted.
  ReferralModerationBulkRequest:
    description: A request to perform one or several moderation actions
    required:
      - actions
    properties:
      actions:
        type: array
        description: "A list of individual moderation actions for specific referrals. Limited to a maximum of 100 actions per request"
        minItems: 1
        maxItems: 100
        items:
          $ref: "#/definitions/ReferralModerationRequest"
  ReferralModerationRequest:
    description: A request to moderate a single referral
    required:
      - referralId
      - action
    properties:
      referralId:
        type: string
        example: "546270a6e4b0c1871186a920"
        description: "The `id` of the Referral to be moderated"
      action:
        type: string
        example: REFERRED_DENIED
        description: "The type of moderation action."
        enum:
          - APPROVED
          - DENIED
          - REFERRER_APPROVED
          - REFERRED_APPROVED
          - REFERRER_DENIED
          - REFERRED_DENIED

  # Response Types
  Error:
    properties:
      statusCode:
        description: The HTTP status code of the error
        type: integer
        format: int32
        example: 404
      message:
        description: The human-readable description of what went wrong. Use this to help you debug.
        type: string
      apiErrorCode:
        description: A machine error code
        type: string

  VariablesError:
    allOf:
      - $ref: "#/definitions/Error"
      - type: object
        properties:
          validationErrors:
            description: A list of validation errors
            type: array
            items:
              type: string

responses:
  GeneralError:
    description: Unexpected Error
    schema:
      $ref: "#/definitions/Error"
  VariablesErrorResponse:
    description: Variables Update Error
    schema:
      $ref: "#/definitions/VariablesError"
    examples:
      "application/json":
        message: "Your request failed to validate against the current variables schema."
        statusCode: 400
        apiErrorCode: "VALIDATION_FAILED"
        validationErrors:
          - 'object has missing required properties (["emailShareSubject","facebookShareBody","facebookShareSubject","twitterShareBody"])'