openapi: 3.0.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.'
  title: MX Platform Goals API
  version: 0.1.0
servers:
- url: https://api.mx.com
- url: https://int-api.mx.com
security:
- basicAuth: []
tags:
- name: Goals
paths:
  /users/{user_guid}/goals:
    post:
      tags:
      - Goals
      summary: Create a goal
      description: Create a goal. This endpoint accepts the optional `MX-Skip-Webhook` header and `skip_webhook` parameter.
      parameters:
      - name: user_guid
        description: The unique identifier for the user.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoalRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalResponseBody'
    get:
      tags:
      - Goals
      summary: List goals
      description: List all goals a user can set.
      parameters:
      - name: user_guid
        description: The unique identifier for the user.
        in: path
        required: true
        schema:
          type: string
      - name: page
        description: Results are returned in paginated sets, this is the page of the results you would like to view. Defaults to page 1 if no page is specified.
        example: null
        in: query
        required: false
        schema:
          type: string
      - name: records_per_age
        description: The supported range is from 10 to 1000. If the records_per_page parameter is not specified or is outside this range, a default of 25 records per page will be used.
        example: null
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalsResponseBody'
  /users/{user_guid}/goals/{goal_guid}:
    delete:
      tags:
      - Goals
      summary: Delete a goal
      description: Delete a goal.
      parameters:
      - name: goal_guid
        description: The unique identifier for a goal. Defined by MX.
        required: true
        in: path
        schema:
          type: string
      - name: user_guid
        description: The unique identifier for a user.
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: No content
    get:
      tags:
      - Goals
      summary: Read a goal
      description: Read a specific goal.
      parameters:
      - name: goal_guid
        description: The unique identifier for a goal. Defined by MX.
        required: true
        in: path
        schema:
          type: string
      - name: user_guid
        description: The unique identifier for a user.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalResponseBody'
    put:
      tags:
      - Goals
      summary: Update a goal
      description: This endpoint updates a specific goal.
      parameters:
      - name: goal_guid
        description: The unique identifier for a goal. Defined by MX.
        required: true
        in: path
        schema:
          type: string
      - name: user_guid
        description: The unique identifier for a user.
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGoalRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalResponseBody'
  /users/{user_guid}/goals/reposition:
    put:
      tags:
      - Goals
      summary: Reposition goals
      description: This endpoint repositions goal priority levels. If one goal is set to a lower priority, then any other goals need to be adjusted accordingly.
      parameters:
      - name: user_guid
        description: The unique identifier for the user.
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositionRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositionResponseBody'
components:
  schemas:
    GoalRequestBody:
      properties:
        goal:
          $ref: '#/components/schemas/GoalRequest'
      type: object
    RepositionResponseBody:
      properties:
        goals:
          items:
            $ref: '#/components/schemas/GoalsResponse'
          type: array
      type: object
    UpdateGoalRequest:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500.5
          type: number
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          type: string
        meta_type_name:
          description: The category of the goal.
          example: VACATION
          type: string
        name:
          description: The name of the goal.
          example: Save for Europe
          type: string
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T16:37:04.000Z'
          type: string
        has_been_spent:
          description: Determines if the goal has been spent.
          example: false
          type: boolean
        is_complete:
          description: Determines if the goal is complete.
          example: false
          type: boolean
        metadata:
          description: Additional information a partner can store on the goal.
          example: Additional information
          type: string
        position:
          description: The priority of the goal in relation to multiple goals.
          example: 3
          type: integer
        targeted_to_complete_at:
          description: Date and time the goal is to complete. Intended for users to set their own goal completion dates.
          example: '2026-12-08T00:00:00.000Z'
          type: string
      type: object
    GoalsResponseBody:
      properties:
        goals:
          items:
            $ref: '#/components/schemas/GoalsResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      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
    RepositionRequest:
      properties:
        guid:
          description: The unique identifier for the goal. Defined by MX.
          example: GOL-97665947-235c-b213-ca25-8cf0174774f5
          type: string
        position:
          description: The priority of the goal in relation to multiple goals.
          example: 1
          type: integer
      required:
      - guid
      - position
    RepositionRequestBody:
      properties:
        goals:
          items:
            $ref: '#/components/schemas/RepositionRequest'
          type: array
      type: object
    GoalResponseBody:
      properties:
        goal:
          $ref: '#/components/schemas/GoalResponse'
      type: object
    GoalsResponse:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500
          type: number
        current_amount:
          description: The current amount of the goal.
          example: 1651.27
          type: number
        guid:
          description: The unique identifier for the goal. Defined by MX.
          example: GOL-524ca5db-a2d5-44f3-b048-16de16059024
          type: string
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          type: string
        meta_type_name:
          description: The category of the goal.
          example: VACATION
          type: string
        name:
          description: The name of the goal.
          example: Save for Europe
          type: string
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T16:37:04.000Z'
          type: string
        has_been_spent:
          description: Determines if the goal has been spent.
          example: false
          type: boolean
        is_complete:
          description: Determines if the goal is complete.
          example: false
          type: boolean
        metadata:
          description: Additional information a partner can store on the goal.
          example: Additional information
          type: string
        position:
          description: The priority of the goal in relation to multiple goals.
          example: 3
          type: integer
        projected_to_complete_at:
          description: The date on which the project was completed.
          example: '2022-06-14T16:03:53.000Z'
          type: string
        targeted_to_complete_at:
          example: '2026-12-08T00:00:00.000Z'
          type: string
        track_type_name:
          example: Track Type Name
          type: string
        user_guid:
          description: The unique identifier for the the user. Defined by MX.
          example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c
          type: string
    GoalResponse:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500
          type: number
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T16:37:04.000Z'
          type: string
        current_amount:
          description: The current amount of the goal.
          example: 1651.27
          type: number
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          type: string
        guid:
          description: Unique identifier for the goal. Defined by MX.
          example: GOL-f223463-4355-48d0-rce7-fe2rb345617c
          type: string
        has_been_spent:
          description: Determines if the goal has been spent.
          example: false
          type: boolean
        is_complete:
          description: Determines if the goal is complete.
          example: false
          type: boolean
        metadata:
          description: Additional information a partner can store on the goal.
          example: Additional information
          type: string
        meta_type_name:
          description: The category of the goal.
          example: VACATION
          type: string
        name:
          description: The name of the goal.
          example: Save for Europe
          type: string
        position:
          description: The priority of the goal in relation to multiple goals.
          example: 3
          type: integer
        projected_to_complete_at:
          description: Date and time the goal is projected to be completed.
          example: '2022-06-14T16:03:53.000Z'
          type: string
        targeted_to_complete_at:
          description: Date and time the goal is to complete. Intended for users to set their own goal completion dates.
          example: '2026-12-08T00:00:00.000Z'
          type: string
        track_type_name:
          example: Track Type Name
          type: string
        user_guid:
          description: The unique identifier for the the user. Defined by MX.
          example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c
          type: string
    GoalRequest:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500.5
          type: number
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          type: string
        meta_type_name:
          description: The category of the goal.
          example: VACATION
          type: string
        name:
          description: The name of the goal.
          example: Save for Europe
          type: string
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T16:37:04.000Z'
          type: string
        has_been_spent:
          description: Determines if the goal has been spent.
          example: false
          type: boolean
        is_complete:
          description: Determines if the goal is complete.
          example: false
          type: boolean
        metadata:
          description: Additional information a partner can store on the goal.
          example: Additional information
          type: string
        position:
          description: The priority of the goal in relation to multiple goals.
          example: 3
          type: integer
        targeted_to_complete_at:
          description: Date and time the goal is to complete. Intended for users to set their own goal completion dates.
          example: '2026-12-08T00:00:00.000Z'
          type: string
      required:
      - account_guid
      - amount
      - goal_type_name
      - meta_type_name
      - name
      type: object
    UpdateGoalRequestBody:
      properties:
        goal:
          $ref: '#/components/schemas/UpdateGoalRequest'
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http