> ## 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.
# Onboard a Business
## What is a Business?
A **Business** in the GrailPay Payments API represents a business entity who can send or receive ACH transfers. Each business is
uniquely identified by a `uuid` associated with the user, which is returned upon successful onboarding and is required for
future operations such as linking bank accounts and initiating transfers.
Onboarding a business is a core part of working with the GrailPay Payments API. This guide outlines the business onboarding
workflow and provides context for common use cases. For complete request and response schemas, refer to
the [OpenAPI documentation](https://api.grailpay.com/api/documentation#/Users/999c42d45d89d2db1aa6f3585c95a004).
A business is a specialized type of person in the GrailPay Payments API. While the onboarding process is similar to
that of a person, it includes additional fields and requirements. If you are transferring funds on behalf of a
business entity, it must be onboarded using the business registration flow to meet compliance and regulatory
obligations.
***
## Testing
When testing in GrailPay’s sandbox environment, you can create a business as usual. To include a bank account, simply
use any random 12-digit account number along with one of our supported test routing numbers.
For more details, refer to the [Technical Overview](/docs/technical/overview#testing) guide.
***
## Step 1: Collect Business Information
To create a business we need to collect information about the point of contact and the information about the business
itself, you can provide any combination of the following fields:
Point of Contact Information:
* First name ( point of contact for the business )
* Last name ( point of contact for the business )
* Email
* Phone
Business Information:
* Name ( legal name of the business )
* Address ( business address )
While only a bank account is required to create a business, we **strongly recommend** supplying full information to
ensure a smooth onboarding experience and help meet regulatory and compliance standards.
See [OpenAPI documentation](https://api.grailpay.com/api/documentation#/Users/999c42d45d89d2db1aa6f3585c95a004) for the full
payload and optional parameters such as **client\_reference\_id**.
***
## Step 2: Link to a Merchant for Billing Attribution
If you want to associate billable events with a merchant, include the **billing\_merchant\_user\_uuid** in your request
payload. This value should reference a user tied to a KYB-verified merchant. You will receive this UUID when you onboard
the merchant using the [Onboard a Merchant](onboard-a-merchant) endpoint.
**Field:**
`billing_merchant_user_uuid` — UUID of the merchant user that should receive billing attribution.
This enables GrailPay to accurately report on merchant usage and ensures billing traceability across your organization.
While adding a billing user uuid is not required, we **strongly recommend** supplying this information to ensure
accurate tracking of usage for your internal billing purposes.
***
## Step 3: Provide a Bank Account
You can onboard a person with or without a connected bank account. If you choose to provide one, we support two methods:
### Option A: Link a Plaid Account
If you're using Plaid for bank account linking, include the following fields:
* `bank_account.plaid.access_token`
* `bank_account.plaid.account_id`
For integration details, refer to the [OpenAPI documentation](https://api.grailpay.com/api/documentation#/Users/999c42d45d89d2db1aa6f3585c95a004).
### Option B: Manual Entry
You can also onboard a person using manually provided account details:
* `account_number`
* `routing_number`
* `account_name`
* `account_type` (`checking` or `savings`)
#### Real-Time Validation (Recommended)
To reduce fraud risk and ensure funds can be successfully routed, we recommend enabling real-time bank account validation
during onboarding. This feature is powered by our [Account Intelligence](/docs/risk/bank-accounts/account-intelligence) product,
which provides intelligent validation of routing and account numbers at the time of submission.
To enable this, include an actions object in your onboarding request:
```json Success (200) theme={"system"}
{
"actions": {
"account_intelligence": {
"version": "v3",
"name_match": true
}
}
}
```
This validation step confirms that the provided routing and account numbers are both valid and correctly formatted. If
name\_match is enabled, it also checks that the account holder’s name aligns with the expected identity. In addition to
these checks, the response includes a **Risk Score** and a set of decisioning insights that explain how the account was
evaluated.
To understand the full structure of the response and how to interpret the results, refer to
our [Account Intelligence](/docs/risk/bank-accounts/account-intelligence#response) documentation.
Although optional, enabling this validation is strongly recommended for all production integrations to reduce failure
rates and improve payout reliability.
***
## Step 4: Review the Response
Upon success, you’ll receive a response containing:
* The `uuid` of the person related to the business. This uuid is required for future operations such as linking bank accounts and initiating transfers.
* Echoed values such as name and address
* Status of the onboarding
* An account intelligence object (if validation was requested)
Full response schema is available in the [OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/999c42d45d89d2db1aa6f3585c95a004).
***
## Try It Out
You can use the [API Explorer](https://api.grailpay.com/api/documentation#/Users/999c42d45d89d2db1aa6f3585c95a004) to
test onboarding flows interactively. This tool allows you to enter a payload, submit a request, and view the response
in real time.
***
## Questions?
If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).
***