openapi: 3.2.0
info:
  title: Benefits Redemption Rewards Redemption Eligibility API
  description: Enables users to view and redeem their rewards
  version: '3.0'
tags:
- name: Rewards-Redemption-Eligibility
paths:
  /cards/accounts/external/{externalAccountID}/redemption/eligibility:
    summary: Rewards API for fetching redemption eligibility.
    description: Rewards API for fetching redemption eligibility.
    get:
      tags:
      - Rewards-Redemption-Eligibility
      summary: Retrieves redemption eligibility information based on available redemption…
      description: Retrieves redemption eligibility information on available redemption options for a specific external account.
      operationId: getRedemptionEligibility
      parameters:
      - name: Correlation-ID
        in: header
        description: 'Unique identifier for each incoming request. The API caller must pass this in the header, which will be cascaded through the API call stack.

          This is required to maintain compliance with the current Barclays REST standards.'
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: externalAccountID
        in: path
        description: A unique id (similar to UUID) created for each customer account.
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 36
          minLength: 1
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: 0dbcb7ee-6c59-483b-966a-44d11557665b
      - name: includeCashBackACHEligibility
        in: query
        description: Include Cash Back ACH redemption eligibility information
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
        example: true
      - name: includeCashBackStmntCrEligibility
        in: query
        description: Include Cash Back Statement credit redemption eligibility information
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
        example: true
      - name: includePayWithPointsEligibility
        in: query
        description: Include Pay With Points redemption eligibility information
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
        example: true
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/RedemptionEligibilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      deprecated: false
components:
  schemas:
    ExternalAccount:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains details of external bank accounts configured on an account for ACH
      properties:
        id:
          type: string
          description: External account identifier
          example: 12311da
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: false
        accountAlias:
          type: string
          description: User-defined account alias
          example: AAA Bank
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: false
        bankName:
          type: string
          description: Name of the bank
          example: Barclays
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: false
        last4Digits:
          type: number
          description: Last 4 digits of account number
          example: 1234
        accountType:
          type: string
          description: Type of bank account
          example: CHECKING
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: false
      required:
      - accountAlias
      - accountType
      - bankName
      - id
      - last4Digits
      nullable: false
    ErrorResponseType:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'An API error response.

        '
      properties:
        meta:
          type: object
          additionalProperties: true
          description: Contains Non-standard meta information
        errors:
          type: array
          description: 'Contains one or more error messages and is mutually exclusive with the data item.

            This will not be returned in success scenarios.

            '
          items:
            $ref: '#/components/schemas/ErrorType'
          maxItems: 50
          minItems: 0
      nullable: false
    PayWithPoints:
      type: object
      additionalProperties: false
      deprecated: false
      description: Pay With Points redemption eligibility information (only present if query parameter includePayWithPointsEligibility=true)
      properties:
        eligibility:
          $ref: '#/components/schemas/Eligibility'
        remainingLimit:
          $ref: '#/components/schemas/RemainingLimit'
      required:
      - eligibility
      nullable: true
    RedemptionEligibilityResponse:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains redemption eligibility information based on available redemption options for a specific external account.
      properties:
        isAccountStatusValid:
          type: boolean
          description: True if account is eligible to redeem the current rewards balance, determined based on if the account is in good standing with regards to account statuses.
          example: true
        cashBackACH:
          $ref: '#/components/schemas/CashBackACH'
        cashBackStmntCr:
          $ref: '#/components/schemas/CashBackStmntCr'
        payWithPoints:
          $ref: '#/components/schemas/PayWithPoints'
      required:
      - isAccountStatusValid
      nullable: false
    CashBackACH:
      type: object
      additionalProperties: false
      deprecated: false
      description: Cash Back ACH redemption eligibility information (only present if query parameter includeCashBackACHEligibility=true)
      properties:
        eligibility:
          $ref: '#/components/schemas/Eligibility'
        remainingLimit:
          $ref: '#/components/schemas/RemainingLimit'
        externalAccounts:
          type: array
          description: List of external bank accounts configured for ACH
          items:
            $ref: '#/components/schemas/ExternalAccount'
          maxItems: 100
          minItems: 0
      required:
      - eligibility
      - externalAccounts
      nullable: true
    ErrorType:
      type: object
      additionalProperties: false
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 1c4717c4-d4a5-e3f3-4a71-b868908763ff
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        code:
          type: string
          description: Machine readable, unique code of the message related to particular case within operation execution.
          example: ACCOUNT_NUMBER_NOT_FOUND
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_]{1,100}$
        title:
          type: string
          description: Short description of the error. Not for displaying purposes.
          example: The authorization credentials required for this request are invalid
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,']{1,250}$
        detail:
          type: string
          description: Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,']{1,250}$
      required:
      - code
      - id
      - title
    CashBackStmntCr:
      type: object
      additionalProperties: false
      deprecated: false
      description: Cash Back Statement credit redemption eligibility information (only present if query parameter includeCashBackStmntCrEligibility=true)
      properties:
        eligibility:
          $ref: '#/components/schemas/Eligibility'
        remainingLimit:
          $ref: '#/components/schemas/RemainingLimit'
      required:
      - eligibility
      nullable: true
    RemainingLimit:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains the remaining amount for redemption if a cap amount is configured on redemption option
      properties:
        value:
          type: number
          description: Monetary amount currently available for redemption requests
          example: 100
        currency:
          type: string
          description: Currency code indicating the monetary denomination
          example: USD
          maxLength: 4
          minLength: 1
          pattern: ^[a-zA-Z]{1,4}$
      required:
      - currency
      - value
      nullable: true
    RedemptionEligibilityResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: Redemption Eligibility Response Data
      properties:
        data:
          $ref: '#/components/schemas/RedemptionEligibilityResponse'
      required:
      - data
      nullable: false
    Eligibility:
      type: object
      additionalProperties: false
      deprecated: false
      description: Determines eligibility of redemption option
      properties:
        value:
          type: boolean
          description: Redemption type eligibility determination and reasoning
          example: true
        ineligibilityReason:
          type: string
          description: Reason for ineligibility
          example: No configured accounts
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: true
      required:
      - value
      nullable: false
  examples:
    example-error-429:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: TOO_MANY_REQUESTS
          title: Too many requests
          detail: The client sent too many requests and server is not able to serve them all at the moment
    example-error-403:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: ACCESS_FORBIDDEN
          title: The user is not permitted to access the requested operation and it cannot be completed
          detail: The user is not permitted to access the requested operation and it cannot be completed
    example-error-500:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error
          detail: Downstream service call failure while retrieving rewards balance
    example-error-401:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: UNAUTHORIZED
          title: The authorization credentials required for this request are invalid
          detail: The authorization credentials required for this request are invalid
    example-error-503:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
          detail: Scheduled service outage starting from Wednesday, 04 Jul 2050 0100 GMT until Wednesday, 04 Jul 2050 0500 GMT
    ResponseWithAllRedemptionTypesEligibility:
      value:
        data:
          isAccountStatusValid: true
          cashBackACH:
            eligibility:
              value: true
              ineligibilityReason: null
            remainingLimit:
              value: 100
              currency: USD
            externalAccounts:
            - id: 12311da
              accountAlias: AAA Bank
              bankName: Barclays
              last4Digits: 1234
              accountType: CHECKING
            - id: 45678bc
              accountAlias: Savings Account
              bankName: Chase
              last4Digits: 5678
              accountType: SAVINGS
          cashBackStmntCr:
            eligibility:
              value: true
              ineligibilityReason: null
            remainingLimit:
              value: 100
              currency: USD
          payWithPoints:
            eligibility:
              value: true
              ineligibilityReason: null
            remainingLimit:
              value: 100
              currency: USD
    example-error-404:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found
          detail: Couldn't locate the account
    ResponseWithoutRedemptionTypesEligibility:
      value:
        data:
          isAccountStatusValid: true
    example-error-400-bad-request:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BAD_REQUEST
          title: The request is invalid or not properly formed
          detail: Invalid request, field name does not match with the API spec
  responses:
    BadRequest:
      description: 'The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            BadRequest:
              $ref: '#/components/examples/example-error-400-bad-request'
    InternalServerError:
      description: 'Server encountered an error during processing the request. It''s s a generic error message, given when a more specific message is not available.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            InternalServerError:
              $ref: '#/components/examples/example-error-500'
    RedemptionEligibilityResponse:
      description: Redemption Eligibility Response Data
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RedemptionEligibilityResponseData'
          examples:
            ResponseWithAllRedemptionTypesEligibility:
              $ref: '#/components/examples/ResponseWithAllRedemptionTypesEligibility'
            ResponseWithoutRedemptionTypesEligibility:
              $ref: '#/components/examples/ResponseWithoutRedemptionTypesEligibility'
    ServiceUnavailable:
      description: 'Temporary maintenance of service, try again later. This is a temporary condition which will be alleviated after some delay.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            ServiceUnavailable:
              $ref: '#/components/examples/example-error-503'
    NotFound:
      description: 'Server was unable to locate a resource to complete the operation. This may be temporary or permanent.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            NotFound:
              $ref: '#/components/examples/example-error-404'
    Forbidden:
      description: 'The user is not permitted to access the requested operation and it cannot be completed.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            Forbidden:
              $ref: '#/components/examples/example-error-403'
    Unauthorized:
      description: 'The user could not be authenticated for this request.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            Unauthorized:
              $ref: '#/components/examples/example-error-401'
    TooManyRequests:
      description: 'Server received a large number of requests from a single party in a given amount of time. Client is advised to retry after the agreed cool down period.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            TooManyRequests:
              $ref: '#/components/examples/example-error-429'
  headers:
    Cache-Control:
      description: GIS mandatory response header. This is added by the Cognac sidecar.
      schema:
        type: string
        default: no-cache, no-store, must-revalidate
        deprecated: false
        example: no-cache, no-store, must-revalidate
        maxLength: 35
        minLength: 35
        pattern: ^no-cache, no-store, must-revalidate$
        nullable: false
  securitySchemes:
    ExternalTiaaUsCCAuth:
      type: oauth2
      description: OAuth2.0 Client Credentials Grant authentication using TIAA-US for external APIs
      flows:
        clientCredentials:
          tokenUrl: https://token.tiaa-dev.us.barclays.intranet:8443/as/token.oauth2
          scopes:
            read: read only
            write: write only