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.

Tenants and Organizations

The Moov API offers two groups for organizating Customer 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 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.

Organizations allow for custom underwriting, additional risk tolerances, and advanced access controls for Customer and Account objects. They can be used to keep departments of your company separate or restrict specific underwriting conditions.

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 additonal 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 becasue it allows immediate credential revocation, two-factor verification with that provider and a faster signup flow for users.

Security

Moov continiously 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.

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-User-ID
string
Example: e3cdf999

Unique userID set by an auth proxy or client to identify and isolate objects.

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
string
Enum: "Individual" "Business"

Note if this Customer represents an individual or business

birthDate
required
string <date-time>

Legal date of birth

email
required
string <= 500

Primary email address of customer name@domain.com

SSN
required
string

Customer Social Security Number (SSN)

Array of objects
required
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-29T09:12:33.001Z",
  • "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-29T09:12:33.001Z",
  • "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-User-ID
string
Example: e3cdf999

Unique userID set by an auth proxy or client to identify and isolate objects.

Responses

Response samples

Content type
application/json
{
  • "customerID": "e210a9d6",
  • "firstName": "Robert",
  • "middleName": "Flex",
  • "lastName": "Smith",