MX Technologies rewards API

openapi: 3.2.0
info:
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  description: 'The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.


    Just getting started? See our [use case guides](/use-cases/).

    '
  title: MX Platform accounts Rewards API
  version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: rewards
paths:
  /users/{user_guid}/members/{member_guid}/fetch_rewards:
    post:
      description: Calling this endpoint initiates an aggregation-type event which will gather the member's rewards information, as well as account and transaction information. Rewards data is also gathered with daily background aggregations. Member and Rewards guids are defined by MX.
      operationId: fetchRewards
      parameters:
      - $ref: '#/components/parameters/userGuid'
      - $ref: '#/components/parameters/memberGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/MemberResponseBody'
          description: OK
      summary: Fetch Rewards
      tags:
      - rewards
  /users/{user_guid}/members/{member_guid}/rewards:
    get:
      description: Use this endpoint to list all the `rewards` associated with a specified `member`. Member guids are defined by MX.
      operationId: listRewards
      parameters:
      - $ref: '#/components/parameters/userGuid'
      - $ref: '#/components/parameters/memberGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/RewardsResponseBody'
          description: OK
      summary: List Rewards
      tags:
      - rewards
  /users/{user_guid}/members/{member_guid}/rewards/{reward_guid}:
    get:
      description: Use this endpoint to read a specific `reward` based on its unique GUID. Member and Rewards guids are defined by MX.
      operationId: readRewards
      parameters:
      - $ref: '#/components/parameters/userGuid'
      - $ref: '#/components/parameters/memberGuid'
      - $ref: '#/components/parameters/rewardGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/RewardResponseBody'
          description: OK
      summary: Read Reward
      tags:
      - rewards
  /credit_card_products/{credit_card_product_guid}:
    get:
      description: This endpoint returns the specified `credit_card_product` according to the unique GUID.
      operationId: creditCard
      parameters:
      - $ref: '#/components/parameters/creditCardProductGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/CreditCardProductResponse'
          description: OK
      summary: Read a Credit Card Product
      tags:
      - rewards
  /users/{user_identifier}/members/{member_identifier}/fetch_rewards:
    post:
      description: Calling this endpoint initiates an aggregation-type event which will gather the member's rewards information, as well as account and transaction information. Rewards data is also gathered with daily background aggregations. Member and Rewards guids are defined by MX.
      operationId: fetchRewards
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userIdentifier'
      - $ref: '#/components/parameters/memberIdentifier'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponseBody'
          description: OK
      summary: Fetch Rewards
      tags:
      - rewards
components:
  parameters:
    memberGuid:
      description: The unique id for a `member`.
      example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
      in: path
      name: member_guid
      required: true
      schema:
        type: string
    memberIdentifier:
      description: Use either the member `id` you defined or the MX-defined member `guid`. See [MX-Defined GUIDs vs IDs Defined by You](https://docs.mx.com/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you).
      name: member_identifier
      in: path
      required: true
      schema:
        type: string
    rewardGuid:
      description: The unique identifier for the rewards. Defined by MX.
      example: RWD-fa7537f3-48aa-a683-a02a-b324322f54
      in: path
      name: reward_guid
      required: true
      schema:
        type: string
    userGuid:
      description: The unique identifier for a `user`, beginning with the prefix `USR-`.
      example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
      in: path
      name: user_guid
      required: true
      schema:
        type: string
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: string
        default: v20250224
        example: v20250224
      description: MX Platform API version.
    creditCardProductGuid:
      description: The required `credit_card_product_guid` can be found on the `account` object.
      example: credit_card_product_guid
      in: path
      name: credit_card_product_guid
      required: true
      schema:
        type: string
    userIdentifier:
      description: Use either the user `id` you defined or the MX-defined user `guid`. See [MX-Defined GUIDs vs IDs Defined by You​](https://docs.mx.com/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you).
      in: path
      required: true
      name: user_identifier
      schema:
        type: string
  schemas:
    MemberResponse:
      properties:
        aggregated_at:
          example: '2016-10-13T18:07:57.000Z'
          type:
          - string
          - 'null'
        background_aggregation_is_disabled:
          example: false
          type: boolean
        connection_status:
          example: CONNECTED
          type:
          - string
          - 'null'
        connection_status_message:
          example: Connected to MX Bank
          type:
          - string
          - 'null'
        guid:
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          type:
          - string
          - 'null'
        id:
          example: unique_id
          type:
          - string
          - 'null'
        institution_code:
          example: mxbank
          type:
          - string
          - 'null'
        institution_guid:
          example: INST-12345678-90ab-cdef-1234-567890abcdef
          type: string
        is_being_aggregated:
          example: false
          type:
          - boolean
          - 'null'
        is_managed_by_user:
          example: false
          type:
          - boolean
          - 'null'
        is_manual:
          example: false
          type:
          - boolean
          - 'null'
        is_oauth:
          example: false
          type:
          - boolean
          - 'null'
        metadata:
          example: '\"credentials_last_refreshed_at\": \"2015-10-15\'
          type:
          - string
          - 'null'
        most_recent_job_detail_code:
          example: null
          type:
          - integer
          - 'null'
        most_recent_job_detail_text:
          example: null
          type:
          - boolean
          - 'null'
        most_recent_job_guid:
          example: JOB-12345678-90ab-cdef-1234-567890abcdef
          type:
          - boolean
          - 'null'
        name:
          example: MX Bank
          type:
          - string
          - 'null'
        needs_updated_credentials:
          example: false
          type:
          - boolean
          - 'null'
        oauth_window_uri:
          example: https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2
          type:
          - string
          - 'null'
        successfully_aggregated_at:
          example: '2016-10-13T17:57:38.000Z'
          type:
          - string
          - 'null'
        use_cases:
          type: array
          description: The use case associated with the member. Valid values are `PFM` and/or `MONEY_MOVEMENT`. Only set this if you've met with MX and have opted in to using this field.
          items:
            type: string
            enum:
            - MONEY_MOVEMENT
            - PFM
          example:
          - PFM
        user_guid:
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          type:
          - string
          - 'null'
        user_id:
          example: user123
          type:
          - string
          - 'null'
      type: object
    CreditCardProductResponse:
      properties:
        credit_card_product:
          $ref: '#/components/schemas/CreditCardProduct'
      type: object
    PaginationResponse:
      properties:
        current_page:
          example: 1
          type: integer
        per_page:
          example: 25
          type: integer
        total_entries:
          example: 1
          type: integer
        total_pages:
          example: 1
          type: integer
      type: object
    RewardResponseBody:
      properties:
        reward:
          allOf:
          - $ref: '#/components/schemas/MemberElements'
          - $ref: '#/components/schemas/RewardElements'
      type: object
    MemberResponseBody:
      properties:
        member:
          $ref: '#/components/schemas/MemberResponse'
      type: object
    CreditCardProduct:
      properties:
        annual_fee:
          example: 45
          type: number
        duration_of_introductory_rate_on_balance_transfer:
          example: null
          type:
          - integer
          - 'null'
        duration_of_introductory_rate_on_purchases:
          example: null
          type:
          - integer
          - 'null'
        guid:
          example: CCA-b5bcd822-6d01-4e23-b8d6-846a225e714a
          type: string
        has_cashback_rewards:
          example: false
          type: boolean
        has_other_rewards:
          example: true
          type: boolean
        has_travel_rewards:
          example: true
          type: boolean
        has_zero_introductory_annual_fee:
          example: true
          type: boolean
        has_zero_percent_introductory_rate:
          example: false
          type: boolean
        has_zero_percent_introductory_rate_on_balance_transfer:
          example: true
          type: boolean
        is_accepting_applicants:
          example: true
          type: boolean
        is_active_credit_card_product:
          example: true
          type: boolean
        is_small_business_card:
          example: true
          type: boolean
        name:
          example: Chase Credit Card
          type: string
    RewardsResponseBody:
      properties:
        rewards:
          items:
            allOf:
            - $ref: '#/components/schemas/MemberElements'
            - $ref: '#/components/schemas/RewardElements'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    RewardElements:
      properties:
        balance_type:
          example: EXPIRING_BALANCE
          type: string
        balance:
          example: 102
          type: integer
        created_at:
          example: 2020-01-28T21:09:01+0000
          type: string
        description:
          example: A description of the reward.
          type: string
        expires_on:
          example: '2020-02-28'
          type: string
        guid:
          example: RWD-1234
          type: string
        unit_type:
          example: POINTS
          type: string
        updated_at:
          example: '2023-06-01T19:18:06Z'
          type: string
    MemberElements:
      properties:
        account_guid:
          example: ACT-283132a4-1401-486a-909e-1605f1623d11
          type: string
        member_guid:
          example: MBR-54feffb9-8474-47bd-8442-de003910113a
          type: string
        user_guid:
          example: USR-101ad774-288b-44ed-ad16-da87d522ea20
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      scheme: basic
      type: http