Create an account

You can create business or individual accounts for your users (i.e., customers, merchants) by passing the required information to Moov. Requirements differ per account type and requested capabilities.

If you’re requesting the wallet, send-funds, collect-funds, or card-issuing capabilities, you’ll need to:

Send Moov the user platform terms of service agreement acceptance. This can be done upon account creation, or by patching the account using the termsOfService field. If you’re creating a business account with the business type llc, partnership, or privateCorporation, you’ll need to:
Provide business representatives after creating the account.
Patch the account to indicate that business representative ownership information is complete.

Visit our documentation to read more about creating accounts and verification requirements. Note that the mode field (for production or sandbox) is only required when creating a facilitator account. All non-facilitator account requests will ignore the mode field and be set to the calling facilitator’s mode.

To access this endpoint using an access token you’ll need to specify the /accounts.write scope.

POST

/accounts

cURL (Business) Go (Business)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


curl -X POST "https://api.moov.io/accounts" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "accountType": "business",
    "profile": {
      "business": {
        "legalBusinessName": "Whole Body Fitness LLC",
        "businessType": "llc",
        "website": "wbfllc.com"
      }
    },
    "foreignId": "your-correlation-id"
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


mc, _ := moov.NewClient()

mc.CreateAccount(ctx, moov.CreateAccount{
  Type: moov.AccountType_Business,
  Profile: moov.CreateProfile{
    Business: &moov.CreateBusinessProfile{
      Name: "Whole Body Fitness LLC",
      Type: "llc",
      Website: "wbfllc.com",
    },
  },
})

200 400 401 403 404 409 422 429 500 504

The request completed successfully.

{
  "accountID": "53ca67ea-6fd3-423f-9544-ce2404159d33",
  "accountType": "business",
  "createdOn": "2024-12-16T17:55:20.557151867Z",
  "displayName": "Whole Body Fitness LLC",
  "mode": "sandbox",
  "profile": {
    "business": {
      "legalBusinessName": "Whole Body Fitness LLC",
      "ownersProvided": false
    }
  },
  "settings": {
    "achPayment": {
      "companyName": "Whole Body Fitne"
    },
    "cardPayment": {
      "statementDescriptor": "Whole Body Fitness LLC"
    }
  },
  "updatedOn": "2024-12-16T17:55:20.557151867Z",
  "verification": {
    "status": "unverified",
    "verificationStatus": "unverified"
  }
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The server could not understand the request due to invalid syntax.

{
  "error": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request contained missing or expired authentication.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The user is not authorized to make the request.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The requested resource was not found.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request conflicted with the current state of the target resource.

{
  "error": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.

{
  "error": {
    "accountType": "string",
    "capabilities": {
      "0": "first element failed validation..."
    },
    "customerSupport": {
      "address": {
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "country": "string",
        "postalCode": "string",
        "stateOrProvince": "string"
      },
      "email": "string",
      "phone": {
        "countryCode": "string",
        "number": "string"
      },
      "website": "string"
    },
    "foreignID": "string",
    "metadata": "string",
    "profile": {
      "business": {
        "address": {
          "addressLine1": "string",
          "addressLine2": "string",
          "city": "string",
          "country": "string",
          "postalCode": "string",
          "stateOrProvince": "string"
        },
        "businessType": "string",
        "description": "string",
        "doingBusinessAs": "string",
        "email": "string",
        "industryCodes": {
          "mcc": "string",
          "naics": "string",
          "sic": "string"
        },
        "legalBusinessName": "string",
        "phone": {
          "countryCode": "string",
          "number": "string"
        },
        "primaryRegulator": "string",
        "taxID": {
          "ein": {
            "number": "string"
          }
        },
        "website": "string"
      },
      "individual": {
        "address": {
          "addressLine1": "string",
          "addressLine2": "string",
          "city": "string",
          "country": "string",
          "postalCode": "string",
          "stateOrProvince": "string"
        },
        "birthDate": {
          "day": "string",
          "month": "string",
          "year": "string"
        },
        "email": "string",
        "governmentID": {
          "itin": {
            "full": "string",
            "lastFour": "string"
          },
          "ssn": {
            "full": "string",
            "lastFour": "string"
          }
        },
        "name": {
          "firstName": "string",
          "lastName": "string",
          "middleName": "string",
          "suffix": "string"
        },
        "phone": {
          "countryCode": "string",
          "number": "string"
        }
      }
    },
    "settings": {
      "achPayment": {
        "companyName": "string"
      },
      "cardPayment": {
        "statementDescriptor": "string"
      }
    },
    "termsOfService": {
      "manual": {
        "acceptedDate": "string",
        "acceptedDomain": "string",
        "acceptedIP": "string",
        "acceptedUserAgent": "string"
      },
      "token": "string"
    }
  }
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Request was refused due to rate limiting.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed due to an unexpected error.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed because a downstream service failed to respond.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Headers

x-moov-version


      string

API version

Specify an API version.

API versioning follows the format vYYYY.QQ.BB, where

YYYY is the year
QQ is the two-digit month for the first month of the quarter (e.g., 01, 04, 07, 10)
BB is the build number, starting at .01, for subsequent builds in the same quarter.
- For example, v2024.01.00 is the initial release of the first quarter of 2024.

The latest version represents the most recent development state. It may include breaking changes and should be treated as a beta release.

Default: v2024.01.00

Body

application/json

accountType


        string<enum>

required

The type of entity represented by this account.

Possible values: individual, business

profile


        object

required

Show child attributes

business


        object

Show child attributes

legalBusinessName


        string

<=64 characters required

The legal name under which the entity is registered.

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

businessType


        string<enum>

The type of entity represented by this business.

Possible values: soleProprietorship, unincorporatedAssociation, trust, publicCorporation, privateCorporation, llc, partnership, unincorporatedNonProfit, incorporatedNonProfit, governmentEntity

description


        string

[10 to 100] characters

doingBusinessAs


        string

<=64 characters

A registered trade name under which the business operates, if different from its legal name.

email


        string<email>

<=255 characters

industryCodes


        object

Show child attributes

mcc


        string

4 characters

naics


        string

[2 to 6] characters

sic


        string

4 characters

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

primaryRegulator


        string<enum>

If the business is a financial institution, this field describes its primary regulator.

Possible values: OCC, FDIC, NCUA, FRB

taxID


        object

An EIN (employer identification number) for the business. For sole proprietors, an SSN can be used as the EIN.

Show child attributes

ein


        object

required

Show child attributes

number


        string

required

website


        string<uri>

<=100 characters

individual


        object

Show child attributes

name


        object

required

Show child attributes

firstName


        string

<=64 characters required

The individual’s first given name.

lastName


        string

<=64 characters required

The individual’s family name.

middleName


        string

<=64 characters

The individual’s second given name, if any.

suffix


        string

<=20 characters

Suffix of a given name.

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

birthDate


        object

Show child attributes

day


        integer

required

month


        integer

required

year


        integer

required

email


        string<email>

<=255 characters

governmentID


        object

Show child attributes

itin


        object

Show child attributes

full


        string

lastFour


        string

ssn


        object

Show child attributes

full


        string

lastFour


        string

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

capabilities


        array

Possible values: transfers, send-funds, collect-funds, wallet, card-issuing

customerSupport


        object

User-provided information that can be displayed on credit card transactions for customers to use when contacting a customer support team. This data is only allowed on a business account.

Show child attributes

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

email


        string<email>

<=255 characters

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

website


        string<uri>

foreignID


        string

<=64 characters

Optional alias from a foreign/external system which can be used to reference this resource.

metadata


        object

Free-form key-value pair list. Useful for storing information that is not captured elsewhere.

mode


        string<enum>

The operating mode for an account.

Possible values: sandbox, production

settings


        object

User provided settings to manage an account.

Show child attributes

achPayment


        object

Show child attributes

companyName


        string

[1 to 16] characters required

The description that shows up on ACH transactions. This will default to the account’s display name on account creation.

cardPayment


        object

User provided settings to manage card payments. This data is only allowed on a business account.

Show child attributes

statementDescriptor


        string

[4 to 22] characters

The description that shows up on credit card transactions. This will default to the accounts display name on account creation.

termsOfService

Show child attributes

An encrypted value used to record acceptance of Moov’s Terms of Service.

token


        string

Describes the acceptance of the Terms of Service. All data is required, and must be from the user.

acceptedDate


        string<date-time>

The date and time the terms of service were accepted.

acceptedDomain


        string<uri>

acceptedIP


        string<ipv4>

The IP address from which the terms of service were accepted.

acceptedUserAgent


        string

<=255 characters

The user-agent of the user making the request.

Response

application/json

accountID


        string<uuid>

required

Unique identifier for this account.

accountType


        string<enum>

required

The type of entity represented by this account.

Possible values: individual, business

createdOn


        string<date-time>

required

displayName


        string

<=64 characters required

mode


        string<enum>

required

The operating mode for an account.

Possible values: sandbox, production

profile


        object

required

Describes a Moov account profile. A profile will have a business or an individual, depending on the account’s type.

Show child attributes

business


        object

Describes a business.

Show child attributes

legalBusinessName


        string

<=64 characters required

The legal name under which the entity is registered.

ownersProvided


        boolean

required

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

businessType


        string<enum>

The type of entity represented by this business.

description


        string

[10 to 100] characters

doingBusinessAs


        string

<=64 characters

A registered trade name under which the business operates, if different from its legal name.

email


        string<email>

<=255 characters

industryCodes


        object

Show child attributes

mcc


        string

4 characters

naics


        string

[2 to 6] characters

sic


        string

4 characters

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

primaryRegulator


        string<enum>

If the business is a financial institution, this field describes its primary regulator.

Possible values: OCC, FDIC, NCUA, FRB

representatives


        array

Show child attributes

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

birthDateProvided


        boolean

Indicates whether this representative’s birth date has been provided.

createdOn


        string<date-time>

disabledOn


        string<date-time>

email


        string<email>

<=255 characters

governmentIDProvided


        boolean

Indicates whether a government ID (SSN, ITIN, etc.) has been provided for this representative.

name


        object

Show child attributes

firstName


        string

<=64 characters required

The individual’s first given name.

lastName


        string

<=64 characters required

The individual’s family name.

middleName


        string

<=64 characters

The individual’s second given name, if any.

suffix


        string

<=20 characters

Suffix of a given name.

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

representativeID


        string<uuid>

Unique identifier for this representative.

responsibilities


        object

Describes the job responsibilities of a business representative.

Show child attributes

isController


        boolean

Indicates whether this individual has significant management responsibilities within the business.

isOwner


        boolean

If true, this field indicates that the individual has a business ownership stake of at least 25% in the business. If the representative does not own at least 25% of the business, this field should be false.

jobTitle


        string

<=64 characters

ownershipPercentage


        integer

The percentage of ownership this individual has in the business (required if isOwner is true).

updatedOn


        string<date-time>

taxIDProvided


        boolean

Indicates whether a tax ID has been provided for this business.

website


        string<uri>

<=100 characters

individual


        object

Describes an individual.

Show child attributes

name


        object

required

Show child attributes

firstName


        string

<=64 characters required

The individual’s first given name.

lastName


        string

<=64 characters required

The individual’s family name.

middleName


        string

<=64 characters

The individual’s second given name, if any.

suffix


        string

<=20 characters

Suffix of a given name.

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

birthDateProvided


        boolean

Indicates whether this individual’s birth date has been provided.

email


        string<email>

<=255 characters

governmentIDProvided


        boolean

Indicates whether a government ID (SSN, ITIN, etc.) has been provided for this individual.

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

updatedOn


        string<date-time>

required

verification


        object

required

Describes identity verification status and relevant identity verification documents.

Show child attributes

status


        string<enum>

required deprecated

Possible states an account verification can be in.

Possible values: unverified, pending, verified, errored

details


        string<enum>

deprecated

Additional detail for a verification status.

Possible values: failedAutoVerify, docDobMismatch, docNameMismatch, docAddressMismatch, docNumberMismatch, docIncomplete, docFailedRisk, potentialAccountSanctionsMatch, potentialRepresentativeSanctionsMatch, failedOther

documents


        array

Show child attributes

contentType


        string

The document’s MIME type.

documentID


        string<uuid>

parseErrors


        array

Optional array of errors encountered during automated parsing.

type


        string<enum>

Types of documents that can be uploaded.

Possible values: driversLicense, passport, utilityBill, bankStatement

uploadedAt


        string<date-time>

verificationStatus


        string<enum>

deprecated

Possible states an account verification can be in.

Possible values: unverified, pending, resubmit, review, verified, failed

capabilities


        array

Show child attributes

capability


        string

status


        string

customerSupport


        object

User-provided information that can be displayed on credit card transactions for customers to use when contacting a customer support team. This data is only allowed on a business account.

Show child attributes

address


        object

Show child attributes

addressLine1


        string

<=60 characters required

city


        string

<=32 characters required

country


        string

<=2 characters required

postalCode


        string

<=5 characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

email


        string<email>

<=255 characters

phone


        object

Show child attributes

countryCode


        string

<=1 characters

number


        string

<=10 characters

website


        string<uri>

disconnectedOn


        string<date-time>

foreignID


        string

<=64 characters

Optional alias from a foreign/external system which can be used to reference this resource.

metadata


        object

Free-form key-value pair list. Useful for storing information that is not captured elsewhere.

settings


        object

User provided settings to manage an account.

Show child attributes

achPayment


        object

Show child attributes

companyName


        string

[1 to 16] characters required

The description that shows up on ACH transactions. This will default to the account’s display name on account creation.

cardPayment


        object

User provided settings to manage card payments. This data is only allowed on a business account.

Show child attributes

statementDescriptor


        string

[4 to 22] characters

The description that shows up on credit card transactions. This will default to the accounts display name on account creation.

termsOfService


        object

Describes the acceptance of the Terms of Service.

Show child attributes

acceptedDate


        string<date-time>

required

The date and time the terms of service were accepted.

acceptedIP


        string<ipv4>

required

The IP address from which the terms of service were accepted.

cURL (Business) Go (Business)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


curl -X POST "https://api.moov.io/accounts" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "accountType": "business",
    "profile": {
      "business": {
        "legalBusinessName": "Whole Body Fitness LLC",
        "businessType": "llc",
        "website": "wbfllc.com"
      }
    },
    "foreignId": "your-correlation-id"
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


mc, _ := moov.NewClient()

mc.CreateAccount(ctx, moov.CreateAccount{
  Type: moov.AccountType_Business,
  Profile: moov.CreateProfile{
    Business: &moov.CreateBusinessProfile{
      Name: "Whole Body Fitness LLC",
      Type: "llc",
      Website: "wbfllc.com",
    },
  },
})

200 400 401 403 404 409 422 429 500 504

The request completed successfully.

{
  "accountID": "53ca67ea-6fd3-423f-9544-ce2404159d33",
  "accountType": "business",
  "createdOn": "2024-12-16T17:55:20.557151867Z",
  "displayName": "Whole Body Fitness LLC",
  "mode": "sandbox",
  "profile": {
    "business": {
      "legalBusinessName": "Whole Body Fitness LLC",
      "ownersProvided": false
    }
  },
  "settings": {
    "achPayment": {
      "companyName": "Whole Body Fitne"
    },
    "cardPayment": {
      "statementDescriptor": "Whole Body Fitness LLC"
    }
  },
  "updatedOn": "2024-12-16T17:55:20.557151867Z",
  "verification": {
    "status": "unverified",
    "verificationStatus": "unverified"
  }
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The server could not understand the request due to invalid syntax.

{
  "error": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request contained missing or expired authentication.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The user is not authorized to make the request.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The requested resource was not found.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request conflicted with the current state of the target resource.

{
  "error": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.

{
  "error": {
    "accountType": "string",
    "capabilities": {
      "0": "first element failed validation..."
    },
    "customerSupport": {
      "address": {
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "country": "string",
        "postalCode": "string",
        "stateOrProvince": "string"
      },
      "email": "string",
      "phone": {
        "countryCode": "string",
        "number": "string"
      },
      "website": "string"
    },
    "foreignID": "string",
    "metadata": "string",
    "profile": {
      "business": {
        "address": {
          "addressLine1": "string",
          "addressLine2": "string",
          "city": "string",
          "country": "string",
          "postalCode": "string",
          "stateOrProvince": "string"
        },
        "businessType": "string",
        "description": "string",
        "doingBusinessAs": "string",
        "email": "string",
        "industryCodes": {
          "mcc": "string",
          "naics": "string",
          "sic": "string"
        },
        "legalBusinessName": "string",
        "phone": {
          "countryCode": "string",
          "number": "string"
        },
        "primaryRegulator": "string",
        "taxID": {
          "ein": {
            "number": "string"
          }
        },
        "website": "string"
      },
      "individual": {
        "address": {
          "addressLine1": "string",
          "addressLine2": "string",
          "city": "string",
          "country": "string",
          "postalCode": "string",
          "stateOrProvince": "string"
        },
        "birthDate": {
          "day": "string",
          "month": "string",
          "year": "string"
        },
        "email": "string",
        "governmentID": {
          "itin": {
            "full": "string",
            "lastFour": "string"
          },
          "ssn": {
            "full": "string",
            "lastFour": "string"
          }
        },
        "name": {
          "firstName": "string",
          "lastName": "string",
          "middleName": "string",
          "suffix": "string"
        },
        "phone": {
          "countryCode": "string",
          "number": "string"
        }
      }
    },
    "settings": {
      "achPayment": {
        "companyName": "string"
      },
      "cardPayment": {
        "statementDescriptor": "string"
      }
    },
    "termsOfService": {
      "manual": {
        "acceptedDate": "string",
        "acceptedDomain": "string",
        "acceptedIP": "string",
        "acceptedUserAgent": "string"
      },
      "token": "string"
    }
  }
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Request was refused due to rate limiting.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed due to an unexpected error.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed because a downstream service failed to respond.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Create an account

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers