> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ach.netevia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboard a Person
The first step in using our ACH API is onboarding new or existing persons to create user accounts. We will then return
a UUID, which serves as the unique identifier for each person, to be used for further requests. Please note that only
one person can be created per request.
The registration information typically includes details such as the user's email, phone, address etc.
We offer a service to connect customer bank accounts with the Bank Link SDK. Please refer to your
client agreement if this service is included in your service package.
### Account/Routing Validation
We support **account and routing number validation** to prevent failed transactions and fund reversals. This
validation is performed by setting the `validate_account_routing` flag to **true** when onboarding a person with a
custom bank account
### Validation Results:
* **valid:** The account and routing number are valid, and the person is added successfully.
* **invalid:** The account or routing number is invalid, and the person is not added to the application. This
returns an HTTP response code - 406
* **not\_validated:** Validation could not be completed, but the person is still added to the application.
### Billing
Our ACH API supports associating specific billable events with a particular merchant, enabling precise attribution
for billing purposes. This feature allows you to link the **UUID** of a user tied to a merchant *(a business that has
undergone KYB verification)* to the billing event recorded for the API call.
To attribute the billing event to a merchant, include the following parameter in your request payload:
* **billing\_merchant\_user\_uuid:** The unique identifier (UUID) of the user associated with the merchant to whom this
billable event should be attributed.
By leveraging this parameter, you can ensure accurate and detailed tracking of billable events across your integrations.
### Endpoint
POST **/3p/api/v1/register/person**
### Request Payload
```json Request Example theme={"system"}
{
"first_name": "Jack",
"last_name": "Jones",
"billing_merchant_user_uuid": "93740cf6-101d-453d-802e-b7bd034a4306",
"address": {
"line_1": "20 Elmora Ave",
"line_2": "",
"city": "Elizabeth",
"state": "NJ",
"zip": "07202"
}
}
```
```json Request Example #2 ( custom bank account ) theme={"system"}
{
"first_name": "Jack",
"last_name": "Jones",
"address": {
"line_1": "20 Elmora Ave",
"line_2": "",
"city": "Elizabeth",
"state": "NJ",
"zip": "07202"
},
"bank_account": {
"custom": {
"account_number": "12345678901234",
"routing_number": "056008849",
"account_name": "Jack Jones",
"account_type": "checking",
"validate_account_routing": true
}
}
}
```
| Fields | Type | Is Required | Description |
| ----------------------------------------------------- | -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **first\_name** | string | | |
| **last\_name** | string | | |
| **email** | string\|unique | | |
| **phone** | string | | without prefix +1 |
| **client\_reference\_id** | string | | |
| **billing\_merchant\_user\_uuid** | string | no | The UUID of the user associated with the merchant that should be associated with the billable event that is created when onboarding a new person |
| **address.line\_1** | string | | |
| **address.line\_2** | string | | |
| **address.city** | string | | |
| **address.state** | string(2) | | |
| **address.zip** | string | | must consist of 5 digit without any special character |
| **bank\_account.plaid.access\_token** | string | | Plaid user access token |
| **bank\_account.plaid.account\_id** | string | | Plaid user account id |
| **bank\_account.custom.account\_number** | string | | Bank account number *maximum of 17 characters* |
| **bank\_account.custom.routing\_number** | string | | Bank account routing number *9-digit ABA routing transit number associated with the account without any special character* |
| **bank\_account.custom.account\_name** | string | | Name of account in bank |
| **bank\_account.custom.account\_type** | string | | Bank account type *Possible values: savings checking* |
| **bank\_account.custom.account\_routing\_validation** | bool | No | Perform validation on the account and routing number. If validation fails, the person will not be created. |
### Response Object
```json Success (201) theme={"system"}
{
"status": true,
"message": "",
"data": {
"client_reference_id": "",
"uuid": "401c79dd-d38c-4c3a-8edf-1afac5914d2d",
"status": "Approved|On Hold|Rejected",
"first_name": "Jack",
"last_name": "Jones",
"email": null,
"phone": null,
"address": {
"street_address": "20 Elmora Ave",
"additional_address": "",
"city": "Elizabeth",
"state": "NJ",
"country": "US",
"zip": "07202"
},
"created_at": "2023-06-10 14:15:54",
"updated_at": "2023-06-10 14:15:54",
"role": "person",
"valid_account": "valid"
},
"errors": []
}
```
### Errors & Warnings
```json 400 (Bad request) theme={"system"}
{
"status": false,
"message": "Invalid value provided for Accept header.",
"data": null,
"errors": null,
"error_code": {
"type": "client_error",
"subtype": "missing_accept_header"
}
}
-----------------------------------------------------
{
"status": false,
"message": "Plaid account ID couldn't be verified",
"data": null,
"errors": null,
"error_code": null
}
-----------------------------------------------------
{
"status": false,
"message": "Invalid routing_number: 000000001. This routing number has an invalid check digit.",
"data": null,
"errors": null,
"error_code": null
}
```
```json 401 (Unauthorized) theme={"system"}
{
"status": false,
"message": "Invalid token.",
"data": null,
"errors": null,
"error_code": {
"type": "client_error",
"subtype": "unauthorized"
}
}
-----------------------------------------------------
{
"status": false,
"message": "Invalid token format. The token should be in the following format: ID|TOKEN_VALUE. Example: 12345|abcdefg",
"data": null,
"errors": null,
"error_code": {
"type": "client_error",
"subtype": "invalid_token_format"
}
}
-----------------------------------------------------
{
"status": false,
"message": "Invalid token format. The ID in the token must be an integer. Example: 12345|abcdefg",
"data": null,
"errors": null,
"error_code": {
"type": "client_error",
"subtype": "invalid_token_format"
}
}
```
```json 403 (Forbidden) theme={"system"}
{
"status": false,
"message": "You do not have permission to access this resource from your IP address or host.",
"data": null,
"errors": null,
"error_code": {
"type": "client_error"
}
}
```
```json 406 ( Not Acceptable ) theme={"system"}
// When the account or routing number is invalid
{
"status": false,
"message": "The account or routing number provided is invalid",
"data": null,
"errors": null,
"error_code": null
}
// When the UUID passed for billing does not exist
{
"status": false,
"message": "The requested billing merchant user uuid does not exist.",
"data": null,
"errors": null,
"error_code": null
}
// When the UUID passed for billing belongs to a user that has been deleted
{
"status": false,
"message": "The billing merchant is deleted and cannot be used for billing purposes.",
"data": null,
"errors": null,
"error_code": null
}
```
```json 422 (Validation Error) theme={"system"}
{
"status": false,
"message": "The given data was invalid.",
"data": null,
"errors": {
"first_name": [
"The first name must be a string.",
"The first name may not be greater than 56 characters.",
"The first name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
],
"last_name": [
"The last name must be a string.",
"The last name may not be greater than 56 characters.",
"The last name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
],
"email": [
"The email must be a valid email address.",
"The email has already been taken"
],
"phone": [
"The phone must be a string.",
"The phone should consist of 10 digits without the +1 prefix"
],
"address.line_1": [
"The address line 1 must be a string."
],
"address.city": [
"The city name must be a string.",
"The city name may not be greater than 56 characters.",
"The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
],
"address.state": [
"The state must be a string.",
"The state may not be greater than 2 characters.",
"The state must be valid US state"
],
"address.zip": [
"The zip code must be a string.",
"The zip code must consist of 5 digit"
],
"bank_account.plaid": [
"The plaid account id and access token is required",
"If a bank account exists, plaid should not be presented"
],
"bank_account.plaid.access_token": [
"The plaid access token must be a string.",
"The plaid access token is required when plaid is present"
],
"bank_account.plaid.account_id": [
"The plaid account id must be a string.",
"The plaid account id is required when plaid is present"
],
"bank_account.custom": [
"If a plaid account exists, bank account should not be presented",
"The bank account routing number, account number, name of account and account type is required"
],
"bank_account.custom.account_number": [
"The bank account number must be a string.",
"The bank account number is required when bank account is present",
"The bank account number may not be greater than 17 characters."
],
"bank_account.custom.routing_number": [
"The bank routing number must be a number.",
"The bank routing number is required when bank account is present",
"The bank routing number must consist of 9 digit"
],
"bank_account.custom.account_name": [
"The bank account name must be a string.",
"The bank account name is required when bank account is present"
],
"bank_account.custom.account_type": [
"The bank account type must be a string.",
"The bank account type should be either savings or checking"
]
},
"error_code": null
}
```