Moov API (v1)

Download OpenAPI specification:Download

The Moov API is an HTTP API served by Moov Financial, Inc for initiating money movements across the ACH payment rail. We follow RESTful operations and naming conventions with predictable and standard HTTP status codes. We are available to help with onboarding or issues related to our services on the Moov slack organization or via support email.

Organizations

The Moov API offers grouping for Customer, Transfer, and other records. A Tenant is the largest grouping which covers an entire business entity such as an LCC or corporation. Login credentials are tied to a Tenant and is extracted from the credentials provided on each request. An Organization is a grouping within a Tenant designed to represent a sub-entity or department (sales, marketing) and can be used for the entire LLC. On signup a Tenant is created with an Organization within through the web UI.

API requests need an X-Organization header included to properly organize models into their groupings.

Errors

The API will respond with various standard HTTP status codes for errors which indicate how to resolve the request's problem. All errors will be in the application/json Content-Type with the below structure.

{
  "error": "Descriptive message"
}
Status Code Summary Description
200 OK The request was successful.
400 Bad Request The request could not be understood by the server. The Incoming parameters might not be valid.
404 Not Found The requested resource is not found or the credentials are not authorized to access it.
429 Too Many Requests Too many requests have been made in a short period of time. Please make requests at a slower rate or contact us.
500 Server Error The server could not return the representation due to an internal server error.
501 Not Implemented The requested operation is not supported (e.g. supports PUT but not POST etc.)

Content-Type

All requests and responses will be in the application/json MIME Content-Type unless otherwise specified.

Cross-Origin Request Sharing

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).

Versioning

The Moov API is currently using /v1/ as the versioning prefix for all endpoints. This results in a base URI of https://api.moov.io/v1/.

Clients

Currently Moov offers a generated Go client for usage with our API. The OpenAPI specification can be used to generate clients in other languages and we are open to supporting additional languages. Please contact us with feedback or suggestions.

Authorization

The Moov API offers one authorization method via a configured OIDC provider for your Tenant. This provider can be Google, Github, LDAP, or another vendor. We leverage OIDC because it allows immediate credential revocation, two-factor verification with that provider and a faster signup flow for users.

Security

Moov continuously monitors and scans our API services for security and privacy issues, but if you find a security related problem please contact us at security@moov.io.

Authentication

GatewayAuth

JWT that comes from the gateway that validates against the gateways public RSA key

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

LoginAuth

Security Scheme Type API Key
Cookie parameter name: moov-authn

Customers

Endpoints for searching, creating, and verifying individuals according to US government criteria for money movement within the country.

Get customers

Search for customers using different filter parameters

Authorizations:
query Parameters
query
string
Example: query=jane

Optional parameter for searching by customer name

email
string
Example: email=jane@doe.com

Optional parameter for searching by customer email

status
string
Example: status=Verified

Optional parameter for searching by customer status

type
string
Example: type=individual

Optional parameter for searching by customer type

skip
string
Example: skip=10

Optional parameter for searching for customers by skipping over an initial group

count
string
Example: count=20

Optional parameter for searching for customers by specifying the amount to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create customer

Create a Customer object from the given details of a human or business

Authorizations:
header Parameters
X-Request-ID
string
Example: rs4f9915

Optional requestID allows application developer to trace requests through the systems logs

X-Organization
string
Example: org342

Value used to separate and identify models

Request Body schema: application/json
firstName
required
string <= 64

Given Name or First Name

middleName
string <= 64

Middle Name

lastName
required
string

Surname or Last Name

nickName
string

Name Customer is preferred to be called

suffix
string

Customers name suffix. "Jr", "PH.D."

type
required
string
Enum: "individual" "business"

Note if this Customer represents an individual or business

birthDate
string

Legal date of birth

email
required
string <= 500

Primary email address of customer name@domain.com

SSN
string

Customer Social Security Number (SSN)

Array of objects
Array of objects >= 1
object

Map of unique keys associated to values to act as foreign key relationships or arbitrary data associated to a Customer.

Responses

Request samples

Content type
application/json
{
  • "firstName": "Robert",
  • "middleName": "Flex",
  • "lastName": "Smith",
  • "nickName": "Bob",
  • "suffix": "string",
  • "type": "individual",
  • "birthDate": "2016-08-29",
  • "email": "string",
  • "SSN": "111-11-1111",
  • "phones":
    [
    ],
  • "addresses":
    [
    ],
  • "metadata":
    {
    }
}

Response samples

Content type
application/json
{
  • "customerID": "e210a9d6",
  • "firstName": "Robert",
  • "middleName": "Flex",
  • "lastName": "Smith",
  • "nickName": "Bob",
  • "suffix": "string",
  • "type": "individual",
  • "birthDate": "2016-08-29",
  • "status": "Deceased",
  • "email": "string",
  • "phones":
    [
    ],
  • "addresses":
    [
    ],
  • "metadata":
    {
    },
  • "createdAt": "2016-08-29T09:12:33.001Z",
  • "lastModified": "2016-08-29T09:12:33.001Z"
}

Retrieve customer

Get the Customer object and metadata for the customerID.

Authorizations:
path Parameters
customerID
required
string
Example: e210a9d6-d755-4455-9bd2-9577ea7e1081

customerID that identifies this Customer

header Parameters
X-Request-ID
string
Example: rs4f9915

Optional requestID allows application developer to trace requests through the systems logs

X-Organization
string
Example: org342

Value used to separate and identify models

Responses

Response samples