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
4
5


mc, _ := moov.NewClient()

var accountID string

mc.ListCapabilities(ctx, accountID)

1
2
3
4
5


const moov = new Moov(credentialsObject);

const accountID = "accountID";

moov.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": "2024-08-24T14:15:22Z",
  "updatedOn": "2024-08-24T14:15:22Z",
  "disabledOn": "2024-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}" \
  --form \
  -F "file=@/path/to/your/file.txt" \
  -F "filePurpose=business_verification" \
  -F "metadata={\"representative_id\":\"UUID\"}"

You an also upload documents via the Dashboard