> ## 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.
# Manage Users
## Overview
In the GrailPay Payments API, a user can take the form of a **Person**, **Business**, or **Merchant**. These entities work together to
represent the full lifecycle of participants in your ACH flow — from individuals initiating transactions, to businesses
receiving funds, to merchants operating within a platform.
This guide provides a centralized reference for managing users across all three entity types. It includes endpoints for:
* Updating, listing, and retrieving people
* Updating, listing, and retrieving businesses
* Updating, listing, and retrieving merchants
* Deactivating and reactivating merchants
* Deleting a person
Each user record is uniquely identified by a UUID, and many of these endpoints return rich data models, including
associated relationships such as bank accounts, linked entities, and KYB status (where applicable). When deleting a
user (such as a person), the record is logically deleted — meaning it is hidden from the API but retained in the system
for compliance and auditing purposes.
Use this guide to query and manage the users in your platform efficiently.
***
## People
In the GrailPay Payments API, a Person represents an individual user within your platform. A person may be directly involved
in sending or receiving funds, or they may be linked to a Business or Merchant entity as part of an onboarding or
transaction workflow.
This flexible structure allows you to model a wide range of real-world scenarios—from independent users to employees or
representatives acting on behalf of a larger organization. Person records support essential attributes such as name,
contact information, and optional associations to other entities, enabling rich identity and relationship management
across your integration.
A Person can be associated with a Business or Merchant. When retrieving a single Person or
listing all People, there is a relations object in the response that will contain the UUID of the Business or Merchant
associated with that Person.
### List People
To retrieve a list of people, you can use the endpoint that returns all people associated with your vendor. This endpoint
allows you to fetch a paginated list of people, including their UUIDs, names, and email addresses. For complete request
and response schemas, refer to the [List People OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/38b563d2d762e16516d6e2f603607498).
### Fetch a Person
To retrieve a specific person, you will need the UUID of the person you want to retrieve. This endpoint allows you to
fetch detailed information about a person, including their name, email, phone number, and the vendor they are associated
with. For complete request and response schemas, refer to the [Fetch a User OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/47b283e94efa8d2a514c2c9ef98f6077).
### Update a Person
To update a person, you must supply the UUID of the person record you wish to modify along with the fields you intend to
change. This endpoint allows you to update basic identifying information such as name, email, or phone number.
Only fields explicitly passed in the request will be updated — all other fields will remain unchanged. This ensures you
can make partial updates without affecting the full record.
For complete request and response schemas, refer to the [Update Person OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/47c342b6509a1330c4e989b172997b71).
### Delete a Person
To delete a specific person, you will need the UUID of the person you want to delete. This endpoint allows you to
remove a person from the system, which will also make any associated information such as bank accounts, transfers,
and related businesses or merchants inaccessible. For complete request and response schemas, refer to
the [Delete User OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/92a24e030e4c373aa3318a0c883df936).
### Submit Person for KYC
To submit a person for KYC (Know Your Customer) verification, send a POST request to the KYC endpoint with the person's
UUID. KYC verification confirms the identity of an individual and is required for a person to act as the payee in a
[Person to Person transaction](/docs/technical/transactions/create-a-transaction#person-to-person-payments).
This endpoint initiates the verification process. It does not return a verification result — once submitted, the person
proceeds through KYC evaluation, and the outcome is delivered via the
[ComplianceStatusChanged](/docs/technical/webhooks/events#compliance-status-changed-event) webhook event. Submission
alone does not make the person eligible to receive funds: you must wait for the `ComplianceStatusChanged` webhook to
report an `approved` status before using the person as the payee in a Person to Person transaction.
For complete request and response schemas, refer to the [Submit Person for KYC OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/1c835cb00622e64c696c8b000a2cbf6b).
Do not create a Person to Person transaction immediately after submitting a person for KYC. KYC evaluation is
asynchronous — the person is not yet approved when the request returns. Wait for the
[ComplianceStatusChanged](/docs/technical/webhooks/events#compliance-status-changed-event) webhook to report an
`approved` status before using them as a payee, otherwise the transaction will be rejected.
A person only needs to complete KYC when they will receive funds in a Person to Person payment. People who
participate solely as payers, or who transact with a Merchant, do not require KYC.
### Person Statuses
Each person record within the GrailPay Payments API includes a `status` field that reflects their current standing within
the system. This status determines whether they are permitted to participate in transactions and helps guide
workflows related to compliance, fraud mitigation, and lifecycle management.
Below is a list of possible statuses and their meanings:
| Status | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPROVED` | The person is fully verified and approved to send or receive funds. |
| `REJECTED` | The person has been rejected and cannot participate in any transactions. This is a status we add manually and signifies a user that cannot be reinstated. |
| `ON_HOLD_FRAUD_PAYER` | A fraud-related return has been reported by the payer. The person is on hold and cannot transact. You must reach out to customer support to initiate an internal review to reinstate the user. |
| `ON_HOLD_FRAUD_PAYEE` | A fraud-related return has been reported by the payee. The person is on hold and cannot transact. You must reach out to customer support to initiate an internal review to reinstate the user. |
| `ON_HOLD_SANCTIONS` | The person has been flagged for potential sanctions risk. They are on hold and cannot transact. You must reach out to customer support to initiate an internal review to reinstate the user. |
| `SCHEDULED_FOR_DELETE` | A deletion request has been received. The person is scheduled for deletion and cannot transact. |
If a person enters a restricted status such as `ON_HOLD_FRAUD_PAYER`, `ON_HOLD_SANCTIONS`, or `ON_HOLD_FRAUD_PAYEE`,
your system will receive a [PersonStatusChanged](/docs/technical/webhooks/events#person-status-changed-event) webhook
event with details about the change, including reason and suggested next steps. In most cases, you will need to contact
our support team, at [support@grailpay.com](mailto:support@grailpay.com), to resolve the issue and restore the person's
ability to transact.
While the status updates will be delivered via webhook, you can also at any time source the status of a person via
calls to the [Fetch Person](https://api.grailpay.com/api/documentation#/Users/47b283e94efa8d2a514c2c9ef98f6077) or
[List People](https://api.grailpay.com/api/documentation#/Users/38b563d2d762e16516d6e2f603607498) endpoints.
***
## Businesses
In the GrailPay Payments API, a Business is a simple entity type that represents an organization capable of sending or
receiving funds. Unlike Merchants, Businesses do not undergo KYB (Know Your Business) verification. However, they are
modeled separately from People to ensure proper ACH classification and compliance with NACHA regulations.
A Business is automatically associated with a Person when it is onboarded. When retrieving a single Business or
listing all Businesses, there is a relations object in the response that will contain the UUID of the Person associated
with that Business.
### List Businesses
To retrieve a list of all businesses associated with your API token, use the list endpoint. This will return a paginated
array of business records including attributes such as UUID, legal name, and timestamps.
For full request and response definitions, refer to the [List Businesses OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/ba480005cebe89606b2f65d95d3c2585).
### Fetch a Business
To fetch details for a specific business, provide the business UUID. The response will include core attributes and
metadata related to the business entity.
For full request and response definitions, refer to the [Fetch a Business OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/d1c75dfe72809303cc7486abbf4b8d1b).
### Update a Business
To update an existing business, send a PATCH request with the updated fields—such as name, address, or contact
information. This helps maintain accurate records for downstream ACH processing and reporting.
While transactions are typically created using the UUID of the Person associated with a Business, this endpoint
specifically requires the UUID of the Business entity itself.
For full request and response definitions, refer to the [Update a Business OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/a176ef962d231a555656d062a2a9d693).
***
## Merchants
In the GrailPay Payments API, a Merchant is a specialized type of Business that has completed KYB (Know Your Business)
verification. KYB is a regulatory requirement that ensures the identity and legitimacy of a business entity before it
can participate in financial transactions. At least one party in every transaction must be KYB-verified, which is why
Merchants play a critical role in GrailPay's compliance and payment workflows.
Although Merchants are technically a kind of Business, they require additional data during onboarding and are subject to
stricter validation rules. This distinction allows GrailPay to maintain compliance while enabling robust and flexible
transaction models.
A Person is automatically associated with a Merchant when it is onboarded. When retrieving a single Merchant or
listing all Merchants, there is a relations object in the response that will contain the UUID of the Person associated
with that Merchant.
### Compliance Status
Each Merchant record includes a `compliance_status` object that provides a complete view of the Merchant's eligibility
to transact. This object contains the computed Compliance Status along with the underlying verification results that
determine it. The `kyb` field reflects the status of the Merchant's business verification, while the `kyc` array
contains the verification status for each Beneficial Owner associated with the Merchant. The top-level `status` field
represents the overall computed Compliance Status, which must be `approved` for the Merchant to be eligible to transact.
For a detailed explanation of compliance requirements, verification outcomes, and corrective actions, refer to
the [Compliance Status Overview](/docs/resources/compliance-status-overview) guide.
### Example Response
```json theme={"system"}
{
"status": "rejected",
"kyb": {
"status": "approved",
"message": null,
"updated_at": "2025-12-11 13:59:21"
},
"kyc": [
{
"uuid": "7f4e8a02-3d5a-4c3b-b823-d8c3125b3f8d",
"first_name": "John",
"last_name": "Doe",
"status": "approved",
"message": null,
"updated_at": "2025-12-11 13:59:21"
},
{
"uuid": "9e2a7cb7-34c1-4c52-a0df-4f9f5704e6e2",
"first_name": "Jane",
"last_name": "Doe",
"status": "rejected",
"message": "Invalid Address",
"updated_at": "2025-12-11 13:59:21"
}
]
}
```
### Fields
#### Top Level
| Field | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `status` | string | The computed Compliance Status for the Merchant. Possible values: `pending`, `in_review`, `approved`, `rejected` |
| `kyb` | object | The KYB verification result for the Merchant's business entity. |
| `kyc` | array | An array of KYC verification results for each Beneficial Owner associated with the Merchant. |
#### KYB Object
| Field | Type | Description |
| ------------ | ----------- | -------------------------------------------------------------------------------------------- |
| `status` | string | The KYB verification status. Possible values: `pending`, `in_review`, `approved`, `rejected` |
| `message` | string/null | If rejected, contains the reason for rejection. Otherwise `null`. |
| `updated_at` | string | Timestamp of the most recent status update. |
#### KYC Array Items
Each item in the `kyc` array represents a Beneficial Owner and their KYC verification result.
| Field | Type | Description |
| ------------ | ----------- | -------------------------------------------------------------------- |
| `uuid` | string | The unique identifier of the Beneficial Owner. |
| `first_name` | string | The first name of the Beneficial Owner. |
| `last_name` | string | The last name of the Beneficial Owner. |
| `status` | string | The KYC verification status. Possible values: `approved`, `rejected` |
| `message` | string/null | If failed, contains the reason for failure. Otherwise `null`. |
| `updated_at` | string | Timestamp of the most recent status update. |
In the example above, the computed `status` is `rejected` even though the KYB status is `approved`. This is because
one of the Beneficial Owners (Jane Doe) has a KYC status of `rejected`. A Merchant is rejected if **either** KYB
fails **or** any Beneficial Owner fails KYC.
### List Merchants
To retrieve a list of all merchants associated with your API token, use the list endpoint. The response will return a
paginated array of merchant records, including their UUIDs, legal names, and KYB status.
For full request and response definitions, refer to the [List Merchants OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/e7ddae992283223ff98ce4cdea429ce6).
### Fetch a Merchant
To fetch details for a specific merchant, provide the merchant UUID. The response will include all core attributes, as
well as KYB-related fields and associated metadata.
For full request and response definitions, refer to the [Fetch A Merchant OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/c262225bb46c22d700bd9d78a6d1f8bb).
### Update a Merchant
To update an existing merchant, send a PATCH request to the update endpoint with any updated fields—such as legal name,
contact information, or address.
For more information about KYB verification and requirements, refer to the [KYB Overview](/docs/resources/kyb-overview) guide.
When testing in the Sandbox environment, Social Security Numbers (SSNs) must follow specific formatting rules to be
considered valid. The SSN:
* **Cannot** begin with `"000"` or any value in the range `"900–999"`
* **Cannot** have `"00"` as the middle two digits
* **Cannot** end in `"0000"`
Any other valid 9-digit SSN format outside of these constraints is acceptable for testing purposes.
If a merchant's KYB status needs to be corrected or additional data is required to pass KYB checks, this endpoint
should be used to resubmit or correct their business information.
While transactions are typically created using the UUID of the Person associated with a Merchant, this endpoint
specifically requires the UUID of the Merchant entity itself.
For full request and response definitions, refer to the [Update A Merchant OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/6680b96fb19eb86c8aea7805cbada282).
### Deactivate a Merchant
To deactivate a merchant, send a POST request to the deactivate endpoint with the merchant's UUID. Deactivating a
merchant sets the merchant to an inactive state, preventing it from initiating new transactions.
This is useful for temporarily suspending a merchant's ability to transact without removing any data from the system.
Deactivation is **non-destructive** — no data is deleted or modified, and any existing transaction history remains
fully intact. Active transactions in progress at the time of deactivation are not automatically cancelled.
This endpoint is **idempotent**. If a merchant is already inactive, calling the deactivate endpoint will return a
successful response without producing any side effects.
```json theme={"system"}
{
"message": "This merchant has been deactivated and will no longer be able to transact"
}
```
This endpoint requires the UUID of the Merchant entity itself, not the UUID of the associated Person.
For full request and response definitions, refer to the [Deactivate Merchant OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/fd7adf2ef947515bd071a0ab67ffc342).
### Reactivate a Merchant
To reactivate a previously deactivated merchant, send a POST request to the activate endpoint with the merchant's UUID.
Reactivating a merchant restores its ability to initiate transactions.
Reactivation does not alter any historical status records or past transactions — it simply sets the merchant back to an
active operational state going forward.
This endpoint is **idempotent**. If a merchant is already active, calling the activate endpoint will return a
successful response without producing any side effects.
```json theme={"system"}
{
"message": "This merchant has been reactivated and is able to transact"
}
```
This endpoint requires the UUID of the Merchant entity itself, not the UUID of the associated Person.
For full request and response definitions, refer to the [Activate Merchant OpenAPI Documentation](https://api.grailpay.com/api/documentation#/Users/f800ac42a34863bcf448d8400b33d6f7).
***
## Questions?
If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).
***