Moov API (v1)

Download OpenAPI specification:Download

Note: The Moov API and services are under development and could introduce breaking changes while reaching a stable status. We are looking for community feedback so please try out our code, join the slack organization and give us some feedback! We announce releases on the mailing list.

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 one method of authentication -- OAuth2 access tokens. 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.

The Moov API offers many services:

  • Automated Clearing House (ACH) origination and file management
  • Transfers management

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. Create a source Customer
    1. Approve
    2. Create an Account
      1. Verify or Approve
  3. Create a destination Customer
    1. Approve
    2. Create an Account
      1. Verify or Approve
  4. Initiate a Transfer

ACH is implemented a RESTful API enabling ACH transactions to be submitted and received without a deep understanding of a full NACHA file specification. A Customer can initiate a Transfer as either a push (credit) or pull (debit) to another Customer. Customers must have a valid Account account for a Transfer.

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

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

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)

phones
Array of objects
addresses
required
Array of objects >= 1
metadata
object

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

Responses

200

Customer was successfully created

400

Customer was not created, see error(s)

post/v1/customers

Local development

http://localhost:9999/v1/customers

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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
Copy
Expand all Collapse all
{
  • "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.

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

200

A customer objects for the supplied customerID

404

No Customer with the specified customerID was found

get/v1/customers/{customerID}

Local development

http://localhost:9999/v1/customers/{customerID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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"
}

Add customer address

Add an Address onto an existing Customer record

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

customerID of the Customer to add the address onto

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
type
required
string
Enum: "Primary" "Secondary"
address1
required
string

First line of the address

address2
string

Second line of the address

city
required
string
state
required
string [ 2 .. 2 ]

two charcer code of US state

postalCode
required
string
country
required
string
Value: "US"

Responses

200

A customer object

400

Customer address was not updated, see error(s)

post/v1/customers/{customerID}/address

Local development

http://localhost:9999/v1/customers/{customerID}/address

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "type": "Primary",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "postalCode": "string",
  • "country": "US"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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"
}

Update customer metadata

Replace the metadata object for a customer. Metadata is a map of unique keys associated to values to act as foreign key relationships or arbitrary data associated to a Customer.

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

customerID of the Customer to add the metadata onto

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
metadata
required
object

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

Responses

200

A customer object

400

Customer metadata was not updated, see error(s)

put/v1/customers/{customerID}/metadata

Local development

http://localhost:9999/v1/customers/{customerID}/metadata

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "metadata":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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"
}

Update customer status

Update the status for a customer, which can only be updated by authenticated users with permissions.

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

customerID of the Customer to update the CustomerStatus

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
comment
string

Free form comment about the customer status update

status
required
string
Enum: "Deceased" "Rejected" "Unknown" "ReceiveOnly" "Verified"

State of the customer

Responses

200

A customer object

400

Customer status was not updated, see error(s)

put/v1/customers/{customerID}/status

Local development

http://localhost:9999/v1/customers/{customerID}/status

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "comment": "Customer was approved from KYC confirmation",
  • "status": "Deceased"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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":
    [