openapi: 3.2.0
info:
  title: Enterprise Realtime Plaid API
  description: The Enterprise Realtime API service acts as the public API layer for advisor infrastructure, enabling partner-developers to programmatically perform advisor actions.
  version: v1
servers:
- url: https://integrations.altruist.com
  description: API Server
tags:
- name: Plaid
  description: Plaid bank linking operations
paths:
  /api/v1/orgs/{orgId}/users/{userId}/fundingAccounts/plaid:
    post:
      tags:
      - Plaid
      summary: Submit a Plaid bank link
      description: 'Creates a funding account from a Plaid public token obtained after a successful Plaid Link session. The auth type in plaidMetaData must reflect the verification_status Plaid Link returned. ERA always enables AVS validation. Blocked for impersonating sessions. The request is safe to retry: if this bank is already on file for the user, the existing funding account is returned with a 200 instead of a 201.'
      operationId: createPlaidFundingAccount
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlaidFundingAccountRequestV1'
        required: true
      responses:
        '400':
          description: Bank link failed
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '403':
          description: Forbidden or impersonation not allowed
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '422':
          description: Account could not be verified through Plaid
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '501':
          description: Not Implemented
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '502':
          description: Bad Gateway
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '201':
          description: Funding account created successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/FundingAccountV1'
        '200':
          description: This bank was already linked; the existing funding account is returned
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/FundingAccountV1'
  /api/v1/orgs/{orgId}/users/{userId}/fundingAccounts/plaid/linkToken:
    post:
      tags:
      - Plaid
      summary: Create a Plaid link token
      description: Mints a short-lived link token to initialize the Plaid Link SDK on the client side. The consumer must pass this token to the Plaid Link widget, which guides the end user through bank authentication. After a successful bank link, call POST /fundingAccounts/plaid with the resulting public token.
      operationId: createLinkToken
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlaidLinkTokenRequestV1'
      responses:
        '400':
          description: Failed to create Plaid link token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '422':
          description: Unprocessable Entity
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '501':
          description: Not Implemented
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '502':
          description: Bad Gateway
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '201':
          description: Link token created successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PlaidLinkTokenResponseV1'
components:
  schemas:
    CreatePlaidLinkTokenRequestV1:
      type: object
      description: Request body for creating a Plaid link token
      properties:
        redirectUri:
          type: string
          description: OAuth redirect URI. Required only for OAuth-redirect banks (e.g., Chase, Bank of America). Must be pre-registered in the Plaid Dashboard. Omit for non-OAuth banks.
          example: https://your-app.com/oauth-callback
    FundingAccountV1:
      type: object
      properties:
        id:
          type: string
          format: uuid
        accountType:
          type: string
          enum:
          - Checking
          - Savings
          - Unknown
          - Investment
          - Brokerage
          - Credit
          - Depository
          - Loan
          - Other
        routingNumber:
          type: string
        institutionName:
          type: string
        accountNumber:
          type: string
        accountName:
          type: string
        authenticationStatus:
          type: string
          enum:
          - Pending
          - Failed
          - Verified
          - PendingManual
          - PendingVerification
          - PendingOpsReview
          - PendingAdvisorReview
          - PendingDraftSubmission
          - PendingClientReview
          - ClientReviewApproved
          - ClientReviewRejected
          - Unknown
        verificationStatus:
          type: string
          enum:
          - Pending
          - Verified
          - Rejected
          - Canceled
          - Unknown
        accountOwnerName:
          type: string
        locked:
          type: boolean
        created:
          type: string
          format: date-time
    PlaidLinkTokenResponseV1:
      type: object
      description: Plaid link token for initializing the Plaid Link SDK
      properties:
        linkToken:
          type: string
          description: Short-lived token to initialize the Plaid Link widget
          example: link-sandbox-abc123...
    PlaidMetaDataV1:
      type: object
      description: Plaid account metadata returned by the Plaid Link SDK on success
      properties:
        accountMask:
          type: string
          description: Last 4 digits of the bank account number
          example: 1234
          minLength: 1
        accountName:
          type: string
          description: Name of the bank account as returned by Plaid
          example: Checking
          minLength: 1
        accountType:
          type: string
          description: Plaid account subtype in UpperCamelCase
          example: Checking
          minLength: 1
        authType:
          type: string
          description: 'Plaid authentication type, derived from the Plaid Link account''s verification_status: Instant if verified immediately, Automated if pending_automatic_verification, Manual if pending_manual_verification.'
          enum:
          - Instant
          - Automated
          - Manual
          example: Instant
        institutionName:
          type: string
          description: Name of the financial institution
          example: Chase
          minLength: 1
        plaidAccountId:
          type: string
          description: Plaid's internal account identifier
          example: plaid-abc123
          minLength: 1
      required:
      - accountMask
      - accountName
      - accountType
      - authType
      - institutionName
      - plaidAccountId
    ErrorV1:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: '### Error Codes


            | Code   | Description                         |

            |--------|-------------------------------------|

            | **0xx** | **Unknown or Unexpected**          |

            | 0    | Unknown error                         |

            | 40   | Unknown authentication error          |

            | **1xx** | **General**                        |

            | 101  | Invalid input                         |

            | 104  | Not found                             |

            | 140  | Access Denied                         |

            | 141  | Unauthorized                          |

            | 150  | Not implemented                       |

            | **10xx** | **Household**                     |

            | 1000 | Household not found                   |

            | 1001 | Duplicate contact                     |

            | 1002 | Household contact not found           |

            | 1003 | Household contact already exists      |

            | **11xx** | **Account**                       |

            | 1100 | Account not found                     |

            | 1110 | Invalid account group                 |

            | **12xx** | **User**                          |

            | 1200 | User not found                        |

            | 1201 | User profile not found                |

            | **13xx** | **Transfer**                      |

            | 1300 | Transfer not found                    |

            | 1301 | Transfer not supported                |

            | 1302 | Duplicate transfer                    |

            | 1303 | Funding account not found             |

            | 1304 | Duplicate funding account             |

            | **14xx** | **Client Agreement**              |

            | 1400 | Client Agreement not found            |

            | 1401 | Invalid Client Agreement file         |

            | 1402 | Client Agreement could not be updated |

            | **15xx** | **Trusted Contact**               |

            | 1500 | Trusted Contact not found             |

            | **17xx** | **Cash Set Aside**                |

            | 1700 | Cash set aside not found              |

            | 1701 | Cash set aside invalid amount         |

            | 1702 | Cash set aside invalid date           |

            | 1703 | Cash set aside upstream error         |

            | 1704 | Cash set aside cannot be cancelled    |

            | 1705 | Cash set aside invalid account        |

            | **18xx** | **Cash Settings**                 |

            | 1800 | Cash settings not found               |

            '
        message:
          type: string
        requestId:
          type: string
    CreatePlaidFundingAccountRequestV1:
      type: object
      description: Request body for submitting a Plaid bank link
      properties:
        publicToken:
          type: string
          description: One-time token returned by Plaid Link on success
          example: public-sandbox-...
          minLength: 1
        plaidMetaData:
          $ref: '#/components/schemas/PlaidMetaDataV1'
          description: Account metadata returned by Plaid Link on success
      required:
      - plaidMetaData
      - publicToken