Moov Accounts API

openapi: 3.2.0
info:
  title: Moov Accounts API
  termsOfService: https://moov.io/legal/platform-agreement/
  version: '1.0'
  description: 'Operations tagged Accounts across 2 of this provider''s published API definitions: moov-api-openapi.yml, moov-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.moov.io
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Accounts
  description: Create and manage Moov accounts representing individual or business legal entities. Accounts are the foundation for all money movement operations.
paths:
  /tos-token:
    get:
      operationId: generateTosToken
      summary: Generate a terms of service token
      description: Retrieve a short-lived terms of service token required when creating new Moov accounts on behalf of users. The token confirms acceptance of Moov's platform agreement.
      tags:
      - Accounts
      responses:
        '200':
          description: Terms of service token generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TosToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.moov.io
      description: Production Server
  /accounts:
    post:
      operationId: createAccount
      summary: Create an account
      description: Create a new Moov account representing an individual or business legal entity. Accounts are required before linking payment methods or initiating transfers. Include a terms of service token from the /tos-token endpoint.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
      responses:
        '200':
          description: Account created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listAccounts
      summary: List accounts
      description: Retrieve a list of accounts connected to your platform. Supports filtering by name, email, and type to locate specific accounts.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/CountParam'
      - $ref: '#/components/parameters/SkipParam'
      - name: name
        in: query
        description: Filter accounts by display name.
        schema:
          type: string
      - name: email
        in: query
        description: Filter accounts by email address.
        schema:
          type: string
          format: email
      - name: type
        in: query
        description: Filter by account type (individual or business).
        schema:
          type: string
          enum:
          - individual
          - business
      responses:
        '200':
          description: List of accounts returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.moov.io
      description: Production Server
  /accounts/{accountID}:
    get:
      operationId: getAccount
      summary: Retrieve an account
      description: Fetch the full details of a specific Moov account by its unique identifier, including profile information, verification status, and capabilities.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountIDParam'
      responses:
        '200':
          description: Account details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAccount
      summary: Update an account
      description: Modify the profile and settings of an existing Moov account. Only the fields provided in the request body will be updated; omitted fields remain unchanged.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountIDParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: Account updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAccount
      summary: Delete an account
      description: Remove a Moov account and all associated data. This operation is irreversible. Ensure all funds have been disbursed before deleting an account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountIDParam'
      responses:
        '204':
          description: Account deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    parameters:
    - $ref: '#/components/parameters/accountID'
    servers:
    - url: https://api.moov.io
      description: Production Server
  /accounts/{accountID}/connections:
    post:
      operationId: shareAccountConnection
      summary: Share an account connection
      description: Establish a connection between two Moov accounts, enabling the platform account to act on behalf of the connected account for money movement and management operations.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountIDParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountConnectionRequest'
      responses:
        '200':
          description: Account connection established.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountConnection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - $ref: '#/components/parameters/accountID'
    servers:
    - url: https://api.moov.io
      description: Production Server
  /accounts/{accountID}/connected-accounts:
    get:
      operationId: listConnectedAccounts
      summary: List connected accounts
      description: Retrieve all accounts that have been connected to the specified account. Used by platform accounts to enumerate their linked user accounts.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountIDParam'
      responses:
        '200':
          description: Connected accounts returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - $ref: '#/components/parameters/accountID'
    servers:
    - url: https://api.moov.io
      description: Production Server
components:
  schemas:
    Phone:
      type: object
      description: Phone number with country code.
      properties:
        number:
          type: string
          description: Phone number digits without formatting.
          pattern: ^\d{10,15}$
        countryCode:
          type: string
          description: International country calling code (e.g., "1" for US).
    Name:
      type: object
      description: Full name of an individual.
      properties:
        firstName:
          type: string
          description: Given name.
        middleName:
          type: string
          description: Middle name or initial.
        lastName:
          type: string
          description: Family name.
        suffix:
          type: string
          description: Name suffix (e.g., Jr., Sr., III).
    AccountVerification:
      type: object
      description: Identity verification status for a Moov account.
      properties:
        verificationStatus:
          type: string
          description: Current KYC/KYB verification status.
          enum:
          - unverified
          - pending
          - resubmit
          - review
          - verified
          - failed
    IndividualProfile:
      type: object
      description: Profile data for an individual Moov account.
      properties:
        name:
          $ref: '#/components/schemas/Name'
        email:
          type: string
          format: email
          description: Email address of the individual.
        phone:
          $ref: '#/components/schemas/Phone'
        address:
          $ref: '#/components/schemas/Address'
        birthDate:
          type: string
          format: date
          description: Date of birth in ISO 8601 format (YYYY-MM-DD).
        governmentID:
          $ref: '#/components/schemas/GovernmentID'
    IndustryCodes:
      type: object
      description: Industry classification codes for the business.
      properties:
        naics:
          type: string
          description: North American Industry Classification System code.
        sic:
          type: string
          description: Standard Industrial Classification code.
        mcc:
          type: string
          description: Merchant Category Code for card payment processing.
    UpdateAccountRequest:
      type: object
      description: Request body for updating a Moov account. Only provided fields are updated.
      properties:
        profile:
          $ref: '#/components/schemas/AccountProfile'
        metadata:
          type: object
          description: Custom key-value metadata to attach to the account.
          additionalProperties:
            type: string
        foreignID:
          type: string
          description: External identifier from your system.
    BusinessProfile:
      type: object
      description: Profile data for a business Moov account.
      properties:
        legalBusinessName:
          type: string
          description: Registered legal name of the business.
        businessType:
          type: string
          description: Type of business entity.
          enum:
          - soleProprietorship
          - unincorporatedAssociation
          - trust
          - publicCorporation
          - privateCorporation
          - privateCorporation
          - llc
          - partnership
          - unincorporatedNonProfit
          - incorporatedNonProfit
        address:
          $ref: '#/components/schemas/Address'
        phone:
          $ref: '#/components/schemas/Phone'
        email:
          type: string
          format: email
          description: Primary business email address.
        website:
          type: string
          format: uri
          description: Business website URL.
        description:
          type: string
          description: Brief description of the business and its products or services.
        taxID:
          $ref: '#/components/schemas/TaxID'
        industryCodes:
          $ref: '#/components/schemas/IndustryCodes'
    CreateAccountRequest:
      type: object
      description: Request body for creating a new Moov account.
      required:
      - accountType
      - profile
      properties:
        accountType:
          type: string
          description: Whether the account is for an individual or a business.
          enum:
          - individual
          - business
        profile:
          $ref: '#/components/schemas/AccountProfile'
        metadata:
          type: object
          description: Custom key-value metadata to attach to the account.
          additionalProperties:
            type: string
        termsOfService:
          type: object
          description: Terms of service acceptance details.
          properties:
            token:
              type: string
              description: Token obtained from the /tos-token endpoint.
        foreignID:
          type: string
          description: External identifier from your system to associate with this account.
    Error:
      type: object
      description: Standard error response returned by the Moov API.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
        code:
          type: string
          description: Machine-readable error code.
    Capability:
      type: object
      description: A feature or permission that enables specific financial operations on a Moov account, such as the ability to send or receive funds.
      properties:
        capability:
          type: string
          description: Identifier for the capability type (e.g., "transfers.push", "collect-funds").
        accountID:
          type: string
          format: uuid
          description: The account this capability belongs to.
        status:
          type: string
          description: Current activation status of the capability.
          enum:
          - enabled
          - disabled
          - pending
          - in-review
        requirements:
          type: array
          description: List of requirements that must be fulfilled to activate this capability.
          items:
            $ref: '#/components/schemas/CapabilityRequirement'
        disabledReason:
          type: string
          description: Explanation of why the capability is disabled, if applicable.
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the capability was created.
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the capability was last updated.
    AccountConnection:
      type: object
      description: An established connection between two Moov accounts.
      properties:
        accountID:
          type: string
          format: uuid
          description: The account that initiated the connection.
        partnerAccountID:
          type: string
          format: uuid
          description: The connected partner account.
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the connection was created.
    Address:
      type: object
      description: Physical or mailing address.
      properties:
        addressLine1:
          type: string
          description: Primary street address.
        addressLine2:
          type: string
          description: Secondary address line (suite, apartment, etc.).
        city:
          type: string
          description: City name.
        stateOrProvince:
          type: string
          description: Two-letter state or province code.
          maxLength: 2
        postalCode:
          type: string
          description: Postal or ZIP code.
        country:
          type: string
          description: Two-letter ISO 3166-1 alpha-2 country code.
          maxLength: 2
    SsnOrItin:
      type: object
      description: Social Security Number or Individual Taxpayer Identification Number.
      properties:
        full:
          type: string
          description: Full 9-digit SSN or ITIN. Only provided on write; masked on read.
          pattern: ^\d{9}$
        lastFour:
          type: string
          description: Last four digits of the SSN or ITIN.
          pattern: ^\d{4}$
    Account:
      type: object
      description: A Moov account representing a legal entity (individual or business) that can send, receive, and store funds on the platform.
      properties:
        accountID:
          type: string
          format: uuid
          description: Unique identifier for the account.
        accountType:
          type: string
          description: Whether the account belongs to an individual or a business.
          enum:
          - individual
          - business
        displayName:
          type: string
          description: Human-readable name for the account.
        profile:
          $ref: '#/components/schemas/AccountProfile'
        capabilities:
          type: array
          description: List of capabilities enabled on this account.
          items:
            $ref: '#/components/schemas/Capability'
        verification:
          $ref: '#/components/schemas/AccountVerification'
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the account was created.
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the account was last updated.
    CapabilityRequirement:
      type: object
      description: A requirement that must be satisfied to activate a capability.
      properties:
        requirement:
          type: string
          description: Machine-readable identifier for the requirement type.
        errorCode:
          type: string
          description: Error code providing more detail about why the requirement is unmet.
    TosToken:
      type: object
      description: Short-lived token confirming acceptance of Moov's terms of service.
      properties:
        token:
          type: string
          description: The terms of service token to include when creating an account.
        expiresOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the token expires.
    AccountConnectionRequest:
      type: object
      description: Request to share an account connection with another Moov account.
      properties:
        partnerAccountID:
          type: string
          format: uuid
          description: The account ID of the partner to connect with.
    TaxID:
      type: object
      description: Business tax identification number.
      properties:
        ein:
          type: object
          description: Employer Identification Number for US businesses.
          properties:
            number:
              type: string
              description: Full EIN. Only provided on write; masked on read.
              pattern: ^\d{9}$
    GovernmentID:
      type: object
      description: Government-issued identification for KYC verification.
      properties:
        ssn:
          $ref: '#/components/schemas/SsnOrItin'
        itin:
          $ref: '#/components/schemas/SsnOrItin'
    AccountProfile:
      type: object
      description: Profile information for a Moov account.
      properties:
        individual:
          $ref: '#/components/schemas/IndividualProfile'
        business:
          $ref: '#/components/schemas/BusinessProfile'
  responses:
    Unauthorized:
      description: Authentication failed. Ensure a valid Bearer token is provided with the required scopes for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    AccountIDParam:
      name: accountID
      in: path
      required: true
      description: Unique identifier for the Moov account.
      schema:
        type: string
        format: uuid
    SkipParam:
      name: skip
      in: query
      description: Number of results to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    CountParam:
      name: count
      in: query
      description: Maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    accountID:
      name: accountID
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The Moov account identifier.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token obtained from the /oauth2/token endpoint. Include in the Authorization header as "Bearer {token}".
x-refined-from:
- moov-api-openapi.yml
- moov-openapi.yml