Troubleshoot capabilities

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

Use this guide to identify, troubleshoot, and solve issues related to requesting capabilities and the verification and underwriting process.

Identify requirement errors

If Moov is unable to verify account information, we will communicate the errors, or ask for documentation. Outstanding capability requirements and errors will prevent a capability from being enabled. The easiest way to see errors is in the Dashboard, however, you can also use the capabilities GET endpoint.

View errors via API

Pass the accountID to the list capabilities GET endpoint to list outstanding requirements for all capabilities

1
2
3


curl -X GET "https://api.moov.io/accounts/{accountID}/capabilities/" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \

1
2
3
4
5


mc, _ := moov.NewClient()

var accountID string

mc.ListCapabilities(ctx, 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 using the capability GET endpoint. Provide both the accountID and capabilityID in the path.

Address requirement errors

See the table below for more details on possible requirement errors and the 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	Upload 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 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

Satisfy document requirements

Moov may require documentation to verify account data and enable capabilities. Document requirements and data requirements are communicated in both the capabilities 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
7


curl -X POST "https://api.moov.io/accounts/{accountID}/files" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \
  --form \
  -F "file=@/path/to/your/file.txt" \
  -F "filePurpose=business_verification" \
  -F "metadata={\"representative_id\":\"UUID\"}"

You can also upload documents via the Dashboard.