What is a Person?
A Person in the GrailPay ACH API represents an individual who can send or receive ACH transfers. Each person is uniquely identified by auuid
, which is returned upon successful onboarding and is required for future operations
such as linking bank accounts and initiating transfers.
The first step in integrating with the GrailPay ACH API is to onboard a person and this guide outlines the onboarding
workflow and provides context for common use cases. For complete request and response
schemas, refer to the Onboard a Person OpenAPI Documentation.
We do have an alternative onboarding method outside of our API that allows you to create a person using our BankLink
SDK product. This method allows you to embed our bank link SDK directly into your application and users can connect
their bank account using open banking. For more information, see the BankLink SDK documentation.
Testing
When testing in GrailPay’s sandbox environment, you can create a person 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 guide.Step 1: Collect Person Information
To create a person, you can provide any combination of the following fields:- First name
- Last name
- Phone
- Address
While only a bank account is required to create a person, we strongly recommend supplying full information to
ensure a smooth onboarding experience and help meet regulatory and compliance standards.
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 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
Option B: Manual Entry
You can also onboard a person using manually provided account details:account_number
routing_number
account_name
account_type
(checking
orsavings
)
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 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:Step 4: Review the Response
Upon success, you’ll receive a response containing:- The person’s
uuid
- Echoed values such as name and address
- Status of the onboarding
- An account intelligence object (if validation was requested)
Error Handling
The onboarding endpoint may return the following common HTTP status codes:Status Code | Description |
---|---|
400 | Bad Request — e.g., missing headers or malformed request |
401 | Unauthorized — invalid or malformed token |
403 | Forbidden — blocked IP address or restricted access |
406 | Not Acceptable — failed account validation or invalid billing UUID |
422 | Unprocessable Entity — field-level validation errors |