Documentation Powered by ReDoc

Moov API (v1)

Download OpenAPI specification:Download

E-mail: security@moov.io URL: https://groups.google.com/forum/#!forum/moov-users License: Apache 2.0

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 or the OpenAPI editor 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 Receiver 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 Receiver. Originators and Receivers must have a valid Depository account for a Transfer. A Transfer is initiated by an Originator to a Receiver with an amount and flow of funds.

Originator                 ->   Gateway   ->   Receiver
 - OriginatorDepository                         - ReceiverDepository
 - 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

    Monitor

    TODO(adam)

    Check that the moov-io/ach service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/ach/ping

    Production server

    https://api.moov.io//v1/ach/ping

    Moov local development setup

    http://localhost:9000//v1/ach/ping

    Check that the moov-io/auth service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/auth/ping

    Production server

    https://api.moov.io//v1/auth/ping

    Moov local development setup

    http://localhost:9000//v1/auth/ping

    Check that the moov-io/fed service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/fed/ping

    Production server

    https://api.moov.io//v1/fed/ping

    Moov local development setup

    http://localhost:9000//v1/fed/ping

    Check that the moov-io/accounts service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/accounts/ping

    Production server

    https://api.moov.io//v1/accounts/ping

    Moov local development setup

    http://localhost:9000//v1/accounts/ping

    Check that the moov-io/customers service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/customers/ping

    Production server

    https://api.moov.io//v1/customers/ping

    Moov local development setup

    http://localhost:9000//v1/customers/ping

    Check that the moov-io/ofac service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/ofac/ping

    Production server

    https://api.moov.io//v1/ofac/ping

    Moov local development setup

    http://localhost:9000//v1/ofac/ping

    Check that the moov-io/paygate service is running

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

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

    Responses

    200

    Service is running properly

    get /v1/paygate/ping

    Production server

    https://api.moov.io//v1/paygate/ping

    Moov local development setup

    http://localhost:9000//v1/paygate/ping

    User

    Create a new user using an email address not seen before.

    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: application/json
    email
    required
    string

    Email address associated to the User

    password
    required
    string

    Password associated to User

    firstName
    required
    string

    Legal first name

    lastName
    required
    string

    Legal last name

    phone
    required
    string

    Phone number associated to user. Dots, hyphens and spaces are trimmed. +1 is the assumed country code.

    companyUrl
    string <uri>

    Company URL associated to user

    Responses

    200

    User object

    400

    Invalid user information, check error(s).

    500

    Internal error, check error(s) and report the issue.

    post /v1/users/create

    Production server

    https://api.moov.io//v1/users/create

    Moov local development setup

    http://localhost:9000//v1/users/create

    Request samples

    application/json
    Copy
     Expand all Collapse all
    {
    • "email": "string",
    • "password": "string",
    • "firstName": "string",
    • "lastName": "string",
    • "phone": "555.555.5555",
    • "companyUrl": "http://example.com"
    }

    Response samples

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

    Check if a cookie is valid and authentic for a user.

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

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

    Responses

    200

    User object

    403

    Cookie data is invalid or expired. Login required.

    get /v1/users/login

    Production server

    https://api.moov.io//v1/users/login

    Moov local development setup

    http://localhost:9000//v1/users/login

    Attempt to login with an email and password

    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: application/json

    Authenticating with an email and password

    email
    string

    Email address associated to the User

    password
    string

    Password associated to User

    Responses

    200

    Successful login

    400

    Invalid request body, check error(s).

    403

    Invalid email and password combination. Retry with correct information.

    post /v1/users/login

    Production server

    https://api.moov.io//v1/users/login

    Moov local development setup

    http://localhost:9000//v1/users/login

    Request samples

    application/json
    Copy
     Expand all Collapse all
    {
    • "email": "user@example.com",
    • "password": "long_passphrase_unique_per_site"
    }

    Response samples

    application/json
    Copy
     Expand all Collapse all
    {
    • "id": "c05ad98a",
    • "email": "user@example.com",
    • "firstName": "Taylor",
    • "lastName": "Swift",
    • "phone": "555.555.5555",
    • "companyUrl": "https://moov.io",
    • "createdAt": "2006-01-02T15:04:05Z07:00"
    }

    Invalidat a user's cookie(s).

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

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

    Responses

    200

    User cookies are invalidated.

    delete /v1/users/login

    Production server

    https://api.moov.io//v1/users/login

    Moov local development setup

    http://localhost:9000//v1/users/login

    Update a User's profile information

    Authorizations:
    cookieAuth
    path Parameters
    user_id
    required
    string
    Example: "3f2d23ee214"

    Moov API User 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

    User profile information

    firstName
    string

    Legal first name

    lastName
    string

    Legal last name

    phone
    string

    Phone number associated to user. Dots, hyphens and spaces are trimmed. +1 is the assumed country code.

    companyUrl
    string <uri>

    Company URL associated to user

    Responses

    200

    User profile updated

    400

    Invalid request body, check error(s).

    patch /v1/users/{user_id}

    Production server

    https://api.moov.io//v1/users/{user_id}

    Moov local development setup

    http://localhost:9000//v1/users/{user_id}

    Request samples

    application/json
    Copy
     Expand all Collapse all
    {
    • "firstName": "Jane",
    • "lastName": "Doe",
    • "phone": "555.555.5555",
    • "companyUrl": "http://example.com"
    }

    Response samples

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

    OAuth2

    Verify OAuth2 Bearer token

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

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

    Authorization
    required
    string
    Example: "Bearer eB2d415A"

    Responses

    200

    Successfully authorized via OAuth2.

    400

    Invalid OAuth2 access_token, check error(s)

    get /v1/oauth2/authorize

    Production server

    https://api.moov.io//v1/oauth2/authorize

    Moov local development setup

    http://localhost:9000//v1/oauth2/authorize

    Response samples

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

    List OAuth2 clients for the authenticated user

    Authorizations:
    cookieAuth
    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.

    Responses

    200

    OAuth2 client credentials

    500

    Internal error occurred, check error(s).

    get /v1/oauth2/clients

    Production server

    https://api.moov.io//v1/oauth2/clients

    Moov local development setup

    http://localhost:9000//v1/oauth2/clients

    Response samples

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

    Create OAuth2 client credentials

    Authorizations:
    cookieAuth
    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.

    Responses

    200

    Created OAuth2 client credentials

    500

    Internal error occurred, check error(s).

    post /v1/oauth2/client

    Production server

    https://api.moov.io//v1/oauth2/client

    Moov local development setup

    http://localhost:9000//v1/oauth2/client

    Response samples

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

    Generate OAuth2 access token

    Authorizations:
    bearerAuth
    query Parameters
    grant_type
    string
    Default: "client_credentials"
    Value:"client_credentials"

    OAuth2 grant type (must be 'client_credentials')

    client_id
    string

    OAuth2 client ID

    client_secret
    string

    OAuth2 client secret

    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.

    Responses

    200

    OAuth2 Bearer access token

    400

    Missing parameters, check error(s)

    post /v1/oauth2/token

    Production server

    https://api.moov.io//v1/oauth2/token

    Moov local development setup

    http://localhost:9000//v1/oauth2/token

    Response samples

    application/json
    Copy
     Expand all Collapse all
    {
    • "access_token": "FFBDB35EDC67",
    • "expires_in": 7200,
    • "token_type": "Bearer"
    }

    Files

    Gets a list of Files

    Authorizations:
    bearerAuthcookieAuth
    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

    Moov local development setup

    http://localhost:9000//v1/ach/files

    Response samples

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

    Create a new File object

    Authorizations:
    bearerAuthcookieAuth
    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:
    application/json

    Content of the ACH file (in json or raw text)

    id
    string

    File ID

    fileHeader
    required
    object
    batches
    Array of objects
    IATBatches
    Array of objects
    fileControl
    object

    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

    Moov local development setup

    http://localhost:9000//v1/ach/files/create

    Request samples

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

    Response samples

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

    Retrieves the details of an existing File. You need only supply the unique File identifier that was returned upon creation.

    Authorizations:
    bearerAuthcookieAuth
    path Parameters
    file_id
    required
    string
    Example: