> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grailpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Intelligence

## Overview

The Account Intelligence v3 endpoint is part of GrailPay's real-time bank account validation system. It allows you to
determine whether a user's bank account is valid, active, and safe to use — helping you reduce fraud, prevent returns,
and accelerate decision-making.

With a single API call, the endpoint returns a `confidence_score` along with detailed `decisioning_insights` based on
the identity and bank account data you provide. These insights can be used to drive onboarding, funding, and payout
workflows with higher accuracy and lower risk.

When constructing your request, you'll pass an `identity` object that contains either an `individual` or an
`organization`. These two are mutually exclusive — the request will fail if both are included. Use `organization` for
validating business entities and `individual` for people.

While the only required fields are account and routing numbers, we strongly recommend providing as much identity data
as possible. More complete input data results in more meaningful confidence scores and more actionable insights.

<Warning>
  This API is only available for U.S. bank accounts.
</Warning>

For complete request and response definitions, visit the [Account Intelligence OpenAPI Documentation](https://risk-api.grailpay.com/spec/#/Account%20Validation/post_api_v3_accounts_validate).

***

## Actions

By default, every call to this endpoint performs core validation checks on the routing and account numbers. To enrich
the results further, you can optionally include an `actions` object in your request to enable additional validation
layers.

Currently, the following action is supported:

* `name_match`: Compares the provided name in the identity object with the account holder's name on file.

To enable name matching, include the following in your request payload:

```json theme={"system"}
{
  "actions": {
    "account_intelligence": {
      "version": "v3",
      "name_match": true
    }
  }
}
```

This triggers GrailPay's proprietary name-matching engine, which contributes directly to the confidence score and
provides additional clarity on identity matching.

For full request and response examples, see the [Account Intelligence API reference](https://risk-api.grailpay.com/spec/#/Account%20Validation/post_api_v3_accounts_validate).

***

## Feedback

Account Intelligence is a continuously improving system, and its accuracy depends on real-world outcome data from your
integration. The Feedback endpoint allows you to report return events that occurred despite receiving an acceptable risk
score, closing the loop between prediction and outcome.

Submitting feedback is a critical part of getting the most out of Account Intelligence. Feedback data is used for
analytics, model evaluation, and ongoing training — directly improving the accuracy of future risk scores across your
account portfolio. Integrations that consistently submit feedback benefit from more precise, tailored risk assessments
over time.

<Info>
  We strongly recommend incorporating feedback submission into your standard return-handling workflow. Consistent
  feedback is the single most effective way to improve the accuracy of your Account Intelligence results.
</Info>

For complete request and response definitions, visit the [Account Intelligence Feedback OpenAPI Documentation](https://risk-api.grailpay.com/spec/#/Account%20Feedback/post_api_v3_accounts_feedback).

### When to Submit Feedback

You should submit feedback when:

* A transaction results in an unexpected return despite receiving a low-risk Account Intelligence score
* You want to improve the accuracy of future risk evaluations for your account portfolio
* You need to report false negatives for internal tracking and model monitoring

### Request Fields

When submitting feedback, your request payload should include details about the account, the return event, and a
reference to the original Account Intelligence evaluation. Required fields ensure we can accurately link your feedback
to the original prediction, while optional fields provide additional context that strengthens model analysis.

#### Required Fields

The following fields are required to link your feedback to the original Account Intelligence evaluation and the
associated return event.

| Field                  | Type    | Description                                               |
| ---------------------- | ------- | --------------------------------------------------------- |
| `account_number`       | string  | The account number from the original evaluation           |
| `routing_number`       | string  | The routing number from the original evaluation           |
| `outcome_status`       | string  | The outcome status of the transaction                     |
| `return_code`          | string  | The ACH return code received                              |
| `name_match_requested` | boolean | Whether name matching was enabled in the original request |

Additionally, you must include **one** of the following to link to the original prediction:

| Field                  | Type      | Description                                                                                   |
| ---------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `inference_request_id` | UUID      | The request ID returned by GrailPay in the original Account Intelligence response (preferred) |
| `inference_timestamp`  | timestamp | The UTC timestamp of the original request, if the request ID is unavailable                   |

<Note>
  Providing the `inference_request_id` is strongly recommended as it ensures accurate linkage to the original risk
  evaluation.
</Note>

#### Optional Fields

The following fields are not required but provide additional context that strengthens model analysis when available.

| Field                      | Type      | Description                                      |
| -------------------------- | --------- | ------------------------------------------------ |
| `returned_at`              | timestamp | When the return was received                     |
| `transaction_initiated_at` | timestamp | When the transaction was initiated (client-side) |
| `sec_code`                 | string    | The SEC code of the transaction                  |
| `amount`                   | decimal   | The transaction amount                           |
| `direction`                | string    | Transaction direction: `credit` or `debit`       |

***

## Usage Recommendations

* Always pass complete and accurate identity data to maximize result quality.
* Use the `confidence_score` and `decisioning_insights` to guide onboarding and risk workflows.
* Review fields such as `name_match`, `valid_routing_number`, and `negative_transactions_seen` closely when the score is low.
* Submit feedback promptly after a return event occurs to ensure accurate timestamps and traceability.
* Always include the `inference_request_id` when available for precise linkage to the original prediction.
* Provide optional fields like `amount`, `sec_code`, and `direction` when possible to enrich the feedback data.

***

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

***