​
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 a uuid, 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 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
  • Email
  • 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.
See OpenAPI schema for the full payload and optional parameters such as client_reference_id.
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: 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 person onboarding spec.

​
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)
To reduce risk and ensure funds can be properly routed, enable real-time validation by including: 
"validate_account_routing": true
This will check the validity of the routing and account number during onboarding.

​
Validation Outcomes

When validate_account_routing is used, the response includes a valid_account field with one of the following values:
ValueMeaning
validAccount is valid. Person was successfully created.
invalidAccount is invalid. Person was not created. (HTTP 406)
not_validatedCould not validate. Person was created, but account status is unknown.

​
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
  • valid_account field (if validation was enabled)
Full response schema is available in the OpenAPI docs.

​
Error Handling

The onboarding endpoint may return the following common HTTP status codes:
Status CodeDescription
400Bad Request — e.g., missing headers or malformed request
401Unauthorized — invalid or malformed token
403Forbidden — blocked IP address or restricted access
406Not Acceptable — failed account validation or invalid billing UUID
422Unprocessable Entity — field-level validation errors
For complete error formats and examples, visit the OpenAPI endpoint.

​
Try It Out

You can use the API Explorer 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 have questions about onboarding workflows, required fields, or errors you’re seeing in testing, please reach out to your GrailPay contact or submit a support ticket via the portal.