openapi: 3.1.0
info:
title: Moov API
description: >-
The Moov API is a RESTful financial infrastructure platform that enables developers
to integrate money movement capabilities into their applications. The API supports
a full range of financial operations including account management, payment method
onboarding, transfers, sweeps, refunds, dispute resolution, card issuing, and
payment links. It provides capabilities for accepting payments, storing funds in
digital wallets, sending money between accounts, and issuing cards for spend
management. Authentication uses OAuth2 access tokens with permission scopes, and
the API returns JSON responses using standard HTTP response codes.
version: '2026.01.00'
contact:
name: Moov Support
url: https://docs.moov.io/
termsOfService: https://moov.io/legal/platform-agreement/
externalDocs:
description: Moov API Documentation
url: https://docs.moov.io/api/
servers:
- url: https://api.moov.io
description: Production Server
tags:
- name: Accounts
description: >-
Create and manage Moov accounts representing individual or business legal
entities. Accounts are the foundation for all money movement operations.
- name: Authentication
description: OAuth2 access token creation and revocation for API authentication.
- name: Bank Accounts
description: >-
Link and manage bank accounts as funding sources for ACH and RTP transfers.
Includes micro-deposit and instant verification flows.
- name: Capabilities
description: >-
Request and manage capabilities that enable specific financial operations
on an account, such as send-funds or collect-funds.
- name: Cards
description: >-
Link and manage debit and credit cards as payment sources on Moov accounts.
- name: Disputes
description: >-
Manage card payment disputes including evidence submission, acceptance, and
lifecycle tracking for chargeback resolution.
- name: Payment Links
description: >-
Create and manage shareable payment links that allow customers to pay via
card or bank account without custom code.
- name: Payment Methods
description: >-
Retrieve the available payment methods on an account, including bank accounts,
cards, and wallets, which can be used as transfer sources or destinations.
- name: Refunds
description: >-
Create and retrieve refunds for completed card transfers, including full and
partial refund support.
- name: Representatives
description: >-
Manage business representatives associated with a Moov account for KYB
compliance and ownership verification.
- name: Sweeps
description: >-
Configure automatic daily transfers from a Moov wallet to an external bank
account on a set schedule using ACH or RTP rails.
- name: Transfers
description: >-
Initiate and manage money movement between Moov accounts. Supports ACH,
RTP, and card rails with full lifecycle tracking.
- name: Wallets
description: >-
Create and manage Moov digital wallets that hold funds within the platform.
Supports wallet transactions and balance adjustments.
security:
- bearerAuth: []
paths:
/oauth2/token:
post:
operationId: createAccessToken
summary: Create an access token
description: >-
Exchange credentials for an OAuth2 access token. The token must be included
as a Bearer token in the Authorization header for all subsequent API requests.
Include the required scopes to grant permission for the operations you intend
to perform.
tags:
- Authentication
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Access token created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AccessToken'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/oauth2/revoke:
post:
operationId: revokeAccessToken
summary: Revoke an access token
description: >-
Revoke a previously issued OAuth2 access token to invalidate it immediately.
Use this when a token is no longer needed or when rotating credentials.
tags:
- Authentication
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RevokeTokenRequest'
responses:
'204':
description: Token revoked successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/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'
/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'
/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'
/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'
/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'
/accounts/{accountID}/capabilities:
post:
operationId: requestCapabilities
summary: Request capabilities
description: >-
Request one or more capabilities for a Moov account to enable specific
financial operations. Moov will evaluate the request and may require
additional information before granting capabilities.
tags:
- Capabilities
parameters:
- $ref: '#/components/parameters/AccountIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RequestCapabilitiesRequest'
responses:
'200':
description: Capabilities requested successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Capability'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listCapabilities
summary: List capabilities
description: >-
Retrieve all capabilities associated with an account, including their
current status and any outstanding requirements needed for activation.
tags:
- Capabilities
parameters:
- $ref: '#/components/parameters/AccountIDParam'
responses:
'200':
description: Capabilities returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Capability'
'401':
$ref: '#/components/responses/Unauthorized'
/accounts/{accountID}/capabilities/{capabilityID}:
get:
operationId: getCapability
summary: Retrieve a capability
description: >-
Fetch the current status and requirements for a specific capability on a
Moov account. Use this to track onboarding progress for a given feature.
tags:
- Capabilities
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/CapabilityIDParam'
responses:
'200':
description: Capability details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Capability'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: disableCapability
summary: Disable a capability
description: >-
Remove a capability from a Moov account, preventing the associated
financial operations from being performed on that account.
tags:
- Capabilities
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/CapabilityIDParam'
responses:
'204':
description: Capability disabled successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/accounts/{accountID}/representatives:
post:
operationId: addRepresentative
summary: Add a representative
description: >-
Add a business representative to a Moov account for KYB compliance.
Representatives are individuals with significant ownership or control
over the business, as required by FinCEN beneficial ownership rules.
tags:
- Representatives
parameters:
- $ref: '#/components/parameters/AccountIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRepresentativeRequest'
responses:
'200':
description: Representative added successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Representative'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listRepresentatives
summary: List representatives
description: >-
Retrieve all business representatives associated with a Moov account,
including their verification status and ownership details.
tags:
- Representatives
parameters:
- $ref: '#/components/parameters/AccountIDParam'
responses:
'200':
description: Representatives returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Representative'
'401':
$ref: '#/components/responses/Unauthorized'
/accounts/{accountID}/representatives/{representativeID}:
get:
operationId: getRepresentative
summary: Retrieve a representative
description: >-
Fetch the full profile and verification details for a specific business
representative on a Moov account.
tags:
- Representatives
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/RepresentativeIDParam'
responses:
'200':
description: Representative details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Representative'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateRepresentative
summary: Update a representative
description: >-
Modify the information for an existing business representative. Use this
to correct or update personal details, ownership percentages, or contact
information as part of KYB compliance maintenance.
tags:
- Representatives
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/RepresentativeIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRepresentativeRequest'
responses:
'200':
description: Representative updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Representative'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: removeRepresentative
summary: Remove a representative
description: >-
Delete a business representative from a Moov account. This may affect
the account's compliance status and capability eligibility.
tags:
- Representatives
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/RepresentativeIDParam'
responses:
'204':
description: Representative removed successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/accounts/{accountID}/bank-accounts:
post:
operationId: linkBankAccount
summary: Link a bank account
description: >-
Connect a bank account to a Moov account as a funding source for ACH
and RTP transfers. After linking, verify the bank account using either
instant verification or micro-deposits before it can be used for transfers.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinkBankAccountRequest'
responses:
'200':
description: Bank account linked successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listBankAccounts
summary: List bank accounts
description: >-
Retrieve all bank accounts linked to a Moov account, including their
verification status and account details.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
responses:
'200':
description: Bank accounts returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BankAccount'
'401':
$ref: '#/components/responses/Unauthorized'
/accounts/{accountID}/bank-accounts/{bankAccountID}:
get:
operationId: getBankAccount
summary: Retrieve a bank account
description: >-
Fetch the details and verification status of a specific bank account
linked to a Moov account.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
responses:
'200':
description: Bank account details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteBankAccount
summary: Delete a bank account
description: >-
Unlink and remove a bank account from a Moov account. This does not close
the underlying bank account, only removes it from the Moov platform.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
responses:
'204':
description: Bank account deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/accounts/{accountID}/bank-accounts/{bankAccountID}/verify:
post:
operationId: initiateBankAccountVerification
summary: Initiate bank account verification
description: >-
Start the instant verification flow for a linked bank account. This method
uses real-time data to verify the account without requiring micro-deposits,
providing faster time-to-use for the funding source.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
responses:
'200':
description: Bank account verification initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountVerification'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: completeBankAccountVerification
summary: Complete bank account verification
description: >-
Submit the verification code or confirmation to finalize instant verification
of a linked bank account.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteVerificationRequest'
responses:
'200':
description: Bank account verification completed.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getBankAccountVerificationStatus
summary: Get verification status
description: >-
Check the current status of a bank account verification attempt, including
whether it is pending, completed, or has failed.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
responses:
'200':
description: Verification status returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountVerification'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/accounts/{accountID}/bank-accounts/{bankAccountID}/micro-deposits:
post:
operationId: initiateMicroDeposits
summary: Initiate micro-deposits
description: >-
Start the micro-deposit verification process by sending two small amounts
to the linked bank account. The account holder must confirm these amounts
to complete verification.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
responses:
'204':
description: Micro-deposits initiated successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: completeMicroDeposits
summary: Complete micro-deposit verification
description: >-
Confirm the micro-deposit amounts that were sent to the linked bank account
to complete the verification process and activate the bank account for transfers.
tags:
- Bank Accounts
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/BankAccountIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MicroDepositConfirmation'
responses:
'200':
description: Micro-deposit verification completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/accounts/{accountID}/cards:
post:
operationId: linkCard
summary: Link a card
description: >-
Attach a debit or credit card to a Moov account as a payment source.
Card data is handled in a PCI-compliant manner via Moov.js to keep
sensitive card numbers out of developer infrastructure.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/AccountIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinkCardRequest'
responses:
'200':
description: Card linked successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listCards
summary: List cards
description: >-
Retrieve all cards linked to a Moov account, including their status,
card brand, and last four digits.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/AccountIDParam'
responses:
'200':
description: Cards returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Card'
'401':
$ref: '#/components/responses/Unauthorized'
/accounts/{accountID}/cards/{cardID}:
get:
operationId: getCard
summary: Retrieve a card
description: >-
Fetch the details of a specific linked card on a Moov account, including
card type, brand, expiration, and current status.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/CardIDParam'
responses:
'200':
description: Card details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCard
summary: Update a card
description: >-
Update the billing address or other mutable attributes of a linked card
on a Moov account.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/CardIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCardRequest'
responses:
'200':
description: Card updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: disableCard
summary: Disable a card
description: >-
Remove a linked card from a Moov account. Disabled cards can no longer
be used as a payment source for new transfers.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/CardIDParam'
responses:
'204':
description: Card disabled successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/accounts/{accountID}/wallets:
post:
operationId: createWallet
summary: Create a wallet
description: >-
Create a Moov digital wallet for an account to hold funds within the
platform. Wallets serve as an intermediate store of value for money
movement operations.
tags:
- Wallets
parameters:
- $ref: '#/components/parameters/AccountIDParam'
responses:
'200':
description: Wallet created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listWallets
summary: List wallets
description: >-
Retrieve all wallets associated with a Moov account, including their
current balances and currencies.
tags:
- Wallets
parameters:
- $ref: '#/components/parameters/AccountIDParam'
responses:
'200':
description: Wallets returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Wallet'
'401':
$ref: '#/components/responses/Unauthorized'
/accounts/{accountID}/wallets/{walletID}:
get:
operationId: getWallet
summary: Retrieve a wallet
description: >-
Fetch the details and current balance of a specific Moov wallet for
an account.
tags:
- Wallets
parameters:
- $ref: '#/components/parameters/AccountIDParam'
- $ref: '#/components/parameters/WalletIDParam'
responses:
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moov/refs/heads/main/openapi/moov-api-openapi.yml