Troubleshoot capabilities

Learn about capability requirement errors, what they mean, and how to address them in the Moov API or Dashboard.

Identifying requirement errors

If Moov is unable to verify account information, we will communicate the errors, or we will ask for documentation. We surface errors through the capabilities GET endpoint and the Dashboard.

Outstanding capability requirements and errors will prevent a capability from being enabled. Missing requirements and errors are both communicated in the Moov API and the Dashboard.

Viewing errors in the Moov API

Use the capabilities GET endpoint to list outstanding requirements for all capabilities, providing the accountID as shown in the example below.

1
2
curl -X GET "https://api.moov.io/accounts/{accountID}/capabilities/" \
  -H "Authorization: Bearer {token}" \
1
2
3
mc := moov.NewClient()

mc.ListCapabilities(ctx, account.AccountID)
1
2
3
4
5
const moov = new Moov(credentialsObject);

const accountID = "accountID";

moov.accounts.capabilities.list(accountID);

The response will communicate:

  • Outstanding requirements
  • Errors on requirements that were previously submitted

For example, the following response communicates that there was an error on the business EIN requirement.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "capability": "transfers",
  "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
  "status": "enabled",
  "requirements": {
    "currentlyDue": [
      "account.tos-acceptance"
    ],
    "errors": [
      {
        "requirement": "business.ein",
        "errorCode": "failed-automatic-verification"
      }
    ]
  },
  "disabledReason": "string",
  "createdOn": "2019-08-24T14:15:22Z",
  "updatedOn": "2019-08-24T14:15:22Z",
  "disabledOn": "2019-08-24T14:15:22Z"
}

You can also find any outstanding requirements for a single capability by using the GET capability endpoint and providing both the accountID and capabilityID in the path.

You can also view errors in the Dashboard.

Addressing requirement errors

See the table below for more details on possible requirement errors and the next steps for resolving them.

Error Description Next steps
failed-automatic-verification The data provided could not be verified Correct the errored field via API or Dashboard
tax-id-mismatch There was an issue verifying the SSN or TIN Submit a document to Moov with the SSN or TIN. See below for a list of acceptable documents
invalid-address The address could not be verified Correct the errored field via API or Dashboard
address-restricted The address provided is not an acceptable residential address Correct the errored field via API or Dashboard
document-id-mismatch The uploaded ID does not match information provided Upload an updated ID or correct the errored field via API or dashboard
document-date-of-birth-mismatch The date of birth listed on the document does not match the date of birth provided Upload an updated document
document-name-mismatch The name listed on the document does not match the name provided Uploaded an updated document
document-number-mismatch A number listed on the document does not match the number provided Upload an updated document
document-incomplete The document provided has incomplete information Upload a document with complete information
document-failed-risk The document failed to meet a Moov requirement Contact Moov support to resolve the issue
document-illegible The uploaded document is not legible Upload a legible version of the document
document-unsupported The document type is not supported Upload one of the following supported document types: CSV, PNG, JPEG, PDF
document-not-uploaded A document was required, but not uploaded Upload a document for the corresponding requirement
document-corrupt The document was corrupt Upload an uncorrupted version of the document
document-expired The document was expired Upload a non-expired version of the document

Satisfying document requirements

Moov may require documentation to verify account data and enable capabilities. Document requirements and data requirements are communicated the same way in the in the capabilities GET endpoint response or in the Dashboard.

Acceptable documents

Document requirement(s) Acceptable documents
business.document.verification - Articles of Incorporation or Certificate of Formation
- DBA Registration
- Government-issued business license or registration
- EIN confirmation letter or SS4
- individual.document.verification
- representative.{rep-uuid}.document.verification
- Unexpired government issued ID with a photo
- Utility bill from the last 60 days
- Bank statement from the last 60 days
- Residential lease or mortgage statement
- individual.document.tin
- representative.{rep-uuid}.document.tin
- Tax return statement
- SSN/ITIN card
- W2

Uploading documents via Moov API

You can address document requirements by uploading a file using the files POST endpoint. When uploading a file, include a filePurpose to communicate what the document is for. A file can have the following purposes:

filePurpose Description
business_verification Use for documents addressing business verification requirements
representative_verification Use for documents addressing representative verification requirements. Must also include the representativeID in the metadata field.
individual_verification Use for documents addressing individual verification requirements

You can upload a file via API as shown below:

1
2
3
4
5
6
curl -X POST "https://api.moov.io/accounts/{accountID}/files" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "file": "whole-body-fitness-ein.pdf",
    "filePurpose": "business_verification"
  }'\

You an also upload documents via the Dashboard

Summary Beta