Moov API (v1)

Download OpenAPI specification:Download

_Note_: We're currently in pre-release of our API. We expect breaking changes before launching v1 so please join our slack organization (request an invite) or mailing list for more updates and notices.

The Moov API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from client-side web applications (never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although you can generate client code via OpenAPI code generation to convert responses to appropriate language-specific objects.

The Moov API offers two methods of authentication, Cookie and OAuth2 access tokens. The cookie auth is designed for web browsers while the OAuth2 authentication is designed for automated access of our API.

When an API requires a token generated using OAuth (2-legged), no end user is involved. You generate the token by passing your client credentials (Client Id and Client Secret) in a simple call to Create access token (/oauth2/token). The operation returns a token that is valid for a few hours and can be renewed; when it expires, you just repeat the call and get a new token. Making additional token requests will keep generating tokens. There are no hard or soft limits.

Cookie auth is setup by provided (/users/login) a valid email and password combination. A Set-Cookie header is returned on success, which can be used in later calls. Cookie auth is required to generate OAuth2 client credentials.

The following order of API operations is suggested to start developing against the Moov API:

  1. Create a Moov API user with a unique email address
  2. Login with user/password credentials
  3. Create an OAuth2 client and Generate an OAuth access token
  4. Using the OAuth credentials create:
  5. Submit the Transfer

After signup clients can submit ACH files (either in JSON or plaintext) for validation and tabulation.

The Moov API offers many services:

  • Automated Clearing House (ACH) origination and file management
  • Transfers and ACH Customer management.
  • X9 / Image Cash Ledger (ICL) specification support (image uplaod)

ACH is implemented a RESTful API enabling ACH transactions to be submitted and received without a deep understanding of a full NACHA file specification.

An Originator can initiate a Transfer as either a push (credit) or pull (debit) to a Customer. Originators and Customers must have a valid Depository account for a Transfer. A Transfer is initiated by an Originator to a Customer with an amount and flow of funds.

Originator                 ->   Gateway   ->   Customer
 - OriginatorDepository                         - CustomerDepository
 - Type   (Push or Pull)
 - Amount (USD 12.43)
 - Status (Pending)

If you find a security related problem please contact us at security@moov.io.

Authentication

bearerAuth

Security scheme type: OAuth2
clientCredentials OAuth Flow
Token URL: https://api.moov.io/v1/oauth2/token
Scopes:

    cookieAuth

    moov_auth Cookie header

    Security scheme type: API Key
    header parameter name: Cookie

    Customers

    Customer objects are an individual or business used to perform transfer's with an originator and track multiple transactions associated with the customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers. (Entry Detail)

    Gets a list of Customers

    Authorizations:
    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A list of Customer objects

    get /v1/ach/customers
    Production server
    https://api.moov.io/v1/ach/customers

    Response samples

    application/json
    Copy
    Expand all Collapse all
    [
    • {
      }
    ]

    Create a new Customer object

    Authorizations:
    header Parameters
    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Request Body schema: application/json
    email
    required
    string <e-mail>

    The customers email address

    defaultDepository
    required
    string

    The depository account to be used by default per transfer. ID must be a valid Customer Depository account

    metadata
    string

    Additional meta data to be used for display only

    Responses

    201

    A JSON object containing a new Customer

    400

    Invalid Customer Object

    post /v1/ach/customers
    Production server
    https://api.moov.io/v1/ach/customers

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "email": "example@moov.io",
    • "defaultDepository": "0c5e215c",
    • "metadata": "Authorized for re-occurring WEB"
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "feb492e6",
    • "email": "string",
    • "defaultDepository": "0c5e215c",
    • "status": "unverified",
    • "metadata": "Authorized for re-occurring WEB",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Get a Customer by ID

    Authorizations:
    path Parameters
    customerId
    required
    string
    Example: "feb492e6"

    Customer ID

    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A Customer object for the supplied Customer ID

    404

    A customer object with the specified ID was not found.

    get /v1/ach/customers/{customerId}
    Production server
    https://api.moov.io/v1/ach/customers/{customerId}

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "feb492e6",
    • "email": "string",
    • "defaultDepository": "0c5e215c",
    • "status": "unverified",
    • "metadata": "Authorized for re-occurring WEB",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Updates the specified Customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

    Authorizations:
    path Parameters
    customerId
    required
    string
    Example: "feb492e6"

    Customer ID

    header Parameters
    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Request Body schema: application/json
    email
    required
    string <e-mail>

    The customers email address

    defaultDepository
    required
    string

    The depository account to be used by default per transfer. ID must be a valid Customer Depository account

    metadata
    string

    Additional meta data to be used for display only

    Responses

    201

    A JSON object containing a new Customer

    400

    Invalid Customer Object

    404

    A customer object with the specified ID was not found.

    patch /v1/ach/customers/{customerId}
    Production server
    https://api.moov.io/v1/ach/customers/{customerId}

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "email": "example@moov.io",
    • "defaultDepository": "0c5e215c",
    • "metadata": "Authorized for re-occurring WEB"
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "feb492e6",
    • "email": "string",
    • "defaultDepository": "0c5e215c",
    • "status": "unverified",
    • "metadata": "Authorized for re-occurring WEB",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Permanently deletes a customer and associated depositories and transfers. It cannot be undone. Immediately cancels any active Transfers for the customer.

    Authorizations:
    path Parameters
    customerId
    required
    string

    Customer ID

    header Parameters
    Authorization
    string
    Example: "Bearer A4CA3074"

    OAuth2 Bearer token

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    Permanently deleted Customer.

    404

    A customer with the specified ID was not found.

    delete /v1/ach/customers/{customerId}
    Production server
    https://api.moov.io/v1/ach/customers/{customerId}

    Get a list of Depository accounts for a Customer

    Authorizations:
    path Parameters
    customerId
    required
    string
    Example: "feb492e6"

    Customer ID

    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A list of Depository objects for a Customer ID

    get /v1/ach/customers/{customerId}/depositories
    Production server
    https://api.moov.io/v1/ach/customers/{customerId}/depositories

    Response samples

    application/json
    Copy
    Expand all Collapse all
    [
    • {
      }
    ]

    Get a Depository accounts for a Customer based on it's ID

    Authorizations:
    path Parameters
    customerId
    required
    string
    Example: "feb492e6"

    Customer ID

    depositoryId
    required
    string
    Example: "0c5e215c"

    Depository ID

    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A Depository objects for the supplied ID

    404

    A resource object with the specified ID was not found.

    get /v1/ach/customers/{customerId}/depositories/{depositoryId}
    Production server
    https://api.moov.io/v1/ach/customers/{customerId}/depositories/{depositoryId}

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "0c5e215c",
    • "bankName": "MVB Bank, Inc.",
    • "holder": "My Company,llc or Wade Arnold",
    • "holderType": "individual",
    • "type": "checking",
    • "routingNumber": "051504597",
    • "accountNumber": "0001027028",
    • "status": "unverified",
    • "metadata": "Payroll",
    • "parent": "feb492e6",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Depositories

    Depository objects represent a US bank or credit union that funds can be debited or credit from a transfer. A Depository must be associated with a customer or an originator. The API allows you to create, delete, and update your depositories. You can retrieve individual depositories as well as a list of all your depositories.

    A list of all Depository objects for the authentication context.

    Authorizations:
    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A list of Depository objects

    get /v1/ach/depositories
    Production server
    https://api.moov.io/v1/ach/depositories

    Response samples

    application/json
    Copy
    Expand all Collapse all
    [
    • {
      }
    ]

    Create a new depository account for a Customer ID or Originator ID defined in the Parent parameter

    Authorizations:
    header Parameters
    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Request Body schema: application/json
    bankName
    required
    string

    Legal name of the financial institution.

    holder
    required
    string

    Legal holder name on the account

    holderType
    required
    string
    Enum:"individual" "company"

    Defines the type of entity of the account holder as an individual or company

    type
    required
    string
    Enum:"Checking" "Savings"

    Defines the account as checking or savings

    routingNumber
    required
    string

    The ABA routing transit number for the depository account.

    accountNumber
    required
    string

    The account number for the depository account

    metadata
    string

    Additional meta data to be used for display only

    parent
    required
    string

    The depository owner's valid Customer ID or Originator ID

    Responses

    201

    Created

    400

    Invalid Depository Object

    post /v1/ach/depositories
    Production server
    https://api.moov.io/v1/ach/depositories

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "bankName": "MVB Bank, Inc.",
    • "holder": "My Company,llc or Wade Arnold",
    • "holderType": "individual",
    • "type": "checking",
    • "routingNumber": "051504597",
    • "accountNumber": "0001027028",
    • "metadata": "Payroll",
    • "parent": "feb492e6"
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "0c5e215c",
    • "bankName": "MVB Bank, Inc.",
    • "holder": "My Company,llc or Wade Arnold",
    • "holderType": "individual",
    • "type": "checking",
    • "routingNumber": "051504597",
    • "accountNumber": "0001027028",
    • "status": "unverified",
    • "metadata": "Payroll",
    • "parent": "feb492e6",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Get a Depository object for the supplied ID

    Authorizations:
    path Parameters
    depositoryId
    required
    string
    Example: "0c5e215c"

    Depository ID

    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A depository object for the supplied ID

    404

    A resource object with the specified ID was not found.

    get /v1/ach/depositories/{depositoryId}
    Production server
    https://api.moov.io/v1/ach/depositories/{depositoryId}

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "0c5e215c",
    • "bankName": "MVB Bank, Inc.",
    • "holder": "My Company,llc or Wade Arnold",
    • "holderType": "individual",
    • "type": "checking",
    • "routingNumber": "051504597",
    • "accountNumber": "0001027028",
    • "status": "unverified",
    • "metadata": "Payroll",
    • "parent": "feb492e6",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Updates the specified Depository by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

    Authorizations:
    path Parameters
    depositoryId
    required
    string
    Example: "feb492e6"

    Depository ID

    header Parameters
    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Request Body schema: application/json
    bankName
    required
    string

    Legal name of the financial institution.

    holder
    required
    string

    Legal holder name on the account

    holderType
    required
    string
    Enum:"individual" "company"

    Defines the type of entity of the account holder as an individual or company

    type
    required
    string
    Enum:"Checking" "Savings"

    Defines the account as checking or savings

    routingNumber
    required
    string

    The ABA routing transit number for the depository account.

    accountNumber
    required
    string

    The account number for the depository account

    metadata
    string

    Additional meta data to be used for display only

    parent
    required
    string

    The depository owner's valid Customer ID or Originator ID

    Responses

    201

    A JSON object containing a new Depository

    400

    Invalid Depository Object

    404

    A resource object with the specified ID was not found.

    patch /v1/ach/depositories/{depositoryId}
    Production server
    https://api.moov.io/v1/ach/depositories/{depositoryId}

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "bankName": "MVB Bank, Inc.",
    • "holder": "My Company,llc or Wade Arnold",
    • "holderType": "individual",
    • "type": "checking",
    • "routingNumber": "051504597",
    • "accountNumber": "0001027028",
    • "metadata": "Payroll",
    • "parent": "feb492e6"
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "0c5e215c",
    • "bankName": "MVB Bank, Inc.",
    • "holder": "My Company,llc or Wade Arnold",
    • "holderType": "individual",
    • "type": "checking",
    • "routingNumber": "051504597",
    • "accountNumber": "0001027028",
    • "status": "unverified",
    • "metadata": "Payroll",
    • "parent": "feb492e6",
    • "created": "2018-12-12T20:25:20Z",
    • "updated": "2018-12-12T20:25:20Z"
    }

    Permanently deletes a depository and associated transfers. It cannot be undone. Immediately cancels any active Transfers for the depository.

    Authorizations:
    path Parameters
    depositoryId
    required
    string

    Depository ID

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    Permanently deleted Depository.

    404

    A depository with the specified ID was not found.

    delete /v1/ach/depositories/{depositoryId}
    Production server
    https://api.moov.io/v1/ach/depositories/{depositoryId}

    Initiates micro deposits to be sent to the Depository institution for account validation

    Authorizations:
    path Parameters
    depositoryId
    required
    string
    Example: "feb492e6"

    Depository ID

    header Parameters
    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    Micro deposits initiated

    400

    Problem initiating micro deposts, see error.

    post /v1/ach/depositories/{depositoryId}/micro-deposits
    Production server
    https://api.moov.io/v1/ach/depositories/{depositoryId}/micro-deposits

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "error": "Validation error(s) present."
    }

    Confirm micro deposit amounts after they have been posted to the depository account

    Authorizations:
    path Parameters
    depositoryId
    required
    string
    Example: "978e6ddb"

    Depository ID

    header Parameters
    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Request Body schema: application/json
    amounts
    required
    Array of string

    Responses

    200

    Micro deposits confirmed

    400

    Invalid Amounts

    404

    A depository with the specified ID was not found.

    409

    Too many attempts. Bank already verified.

    post /v1/ach/depositories/{depositoryId}/micro-deposits/confirm
    Production server
    https://api.moov.io/v1/ach/depositories/{depositoryId}/micro-deposits/confirm

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "amounts":
      [
      ]
    }

    Events

    Event objects are a notification of a state change of a resource. When an Event is created any active webhooks will be notified.

    Gets a list of Events

    Authorizations:
    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    startDate
    string <date-time>

    Filter objects created after this date. ISO-8601 format YYYY-MM-DD. Can optionally be used with endDate to specify a date range.

    endDate
    string <date-time>

    Filter objects created before this date. ISO-8601 format YYYY-MM-DD. Can optionally be used with startDate to specify a date range.

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A list of Event objects

    get /v1/ach/events
    Production server
    https://api.moov.io/v1/ach/events

    Response samples

    application/json
    Copy
    Expand all Collapse all
    [
    • {
      }
    ]

    Get a Event by ID

    Authorizations:
    path Parameters
    eventId
    required
    string
    Example: "94cf1126"

    Event ID

    query Parameters
    offset
    integer >= 1
    Default: 0

    The number of items to skip before starting to collect the result set

    limit
    integer [ 0 .. 100 ]
    Default: 25
    Example: 10

    The number of items to return

    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A Event object for the supplied Customer ID

    404

    A event object with the specified ID was not found.

    get /v1/ach/events/{eventId}
    Production server
    https://api.moov.io/v1/ach/events/{eventId}

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "94cf1126",
    • "topic": "transfer_created",
    • "message": "A bank transfer was created",
    • "type": "Transfers",
    • "resource": "dad7ddfb-71cd-4699-add4-2867878d154f",
    • "created": "2018-12-12T20:25:20Z"
    }

    Files

    File contains the structures of a ACH File. It contains one and only one File Header and File Control with at least one Batch. Batch objects within Files hold the Batch Header and Batch Control and all Entry Records and Addenda records for the Batch.

    Gets a list of Files

    Authorizations:
    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    Responses

    200

    A list of File objects

    get /v1/ach/files
    Production server
    https://api.moov.io/v1/ach/files

    Response samples

    application/json
    Copy
    Expand all Collapse all
    [
    • {
      }
    ]

    Create a new File object

    Authorizations:
    header Parameters
    X-Request-Id
    string
    Example: "rs4f9915"

    Optional Request ID allows application developer to trace requests through the systems logs

    X-Idempotency-Key
    string
    Example: "a4f88150"

    Idempotent key in the header which expires after 24 hours. These strings should contain enough entropy for to not collide with each other in your requests.

    Request Body schema:
    id
    string

    File ID

    fileHeader
    required
    object (FileHeader)
    batches
    Array of object (Batch)
    IATBatches
    Array of object (IATBatch)
    fileControl
    object (FileControl)

    Responses

    201

    A JSON object containing a new File

    400

    Invalid File Header Object

    post /v1/ach/files/create
    Production server
    https://api.moov.io/v1/ach/files/create

    Request samples

    Copy
    Expand all Collapse all
    {
    • "id": "3f2d23ee214",
    • "fileHeader":
      {
      },
    • "batches":
      [
      ],
    • "IATBatches":
      [
      ],
    • "fileControl":
      {
      }
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "3f2d23ee214",
    • "fileHeader":
      {
      },
    • "batches":
      [