> ## 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 new Business or Merchant into the ACH application ( SUNSETTING ) > **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.** ## OpenAPI ````yaml https://api.grailpay.com/docs?api-docs.json post /3p/api/v2/businesses openapi: 3.0.0 info: title: GrailPay ACH API description: API Documentation for moving funds via ACH using the GrailPay ACH API version: 2025.12.19.2 servers: - url: https://api.grailpay.com description: Production environment - url: https://api-sandbox.grailpay.com description: Sandbox environment security: [] tags: - name: Users description: >- API Endpoints used for the onboarding and managing People, Businesses, and Merchants. - name: Transactions description: API Endpoints used for creating and managing transactions. - name: Payouts description: API Endpoints used for fetching payout information. - name: Refunds description: API Endpoints used for creating and retrieving refunds. - name: Bank Accounts description: API Endpoints used for adding and managing bank accounts. - name: Webhooks description: API Endpoints used for registering and de-registering webhooks. - name: Billing description: API Endpoints used for retrieving billing information. - name: Stable description: Stable, up-to-date APIs that are recommended for current integration. - name: Sunsetting description: Sunsetting APIs that are still supported but scheduled for deprecation. - name: Deprecated description: Deprecated APIs that are no longer supported and should be removed. - name: SUNSETTING description: SUNSETTING paths: /3p/api/v2/businesses: post: tags: - Users - Sunsetting summary: >- Onboard a new Business or Merchant into the ACH application ( SUNSETTING ) description: >- **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.** operationId: 7c551c8aa54cc5588db347b998a46df2 requestBody: required: true content: application/json: schema: required: - kyb - client_reference_id - first_name - last_name - email - phone - business properties: kyb: type: boolean example: true client_reference_id: type: string example: '123456' first_name: type: string example: John last_name: type: string example: Doe email: type: string example: test@example.org phone: type: string example: '1234567890' business: $ref: '#/components/schemas/Business' business_owners: type: array items: $ref: '#/components/schemas/BusinessOwner' bank_account: $ref: '#/components/schemas/V2BankAccountRequest' billing_merchant_user_uuid: type: string format: uuid example: 2bcf2ac3-38fc-4238-a638-4f092821fc27 nullable: true billing_processor_mid: type: string example: '21245678932' nullable: true type: object responses: '201': description: Business registered successfully content: application/json: schema: $ref: '#/components/schemas/V2OnboardBusinessResponse' '400': description: Bad Request content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error400' - $ref: '#/components/schemas/Error400InvalidAcceptHeader' - $ref: '#/components/schemas/Error400InvalidPlaidAccount' - $ref: '#/components/schemas/Error400UnverifiedPlaidAccount' - $ref: '#/components/schemas/Error400InvalidRoutingNumber' '401': description: Unauthorized content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error401Unauthorized' - $ref: '#/components/schemas/Error401UnauthorizedProcessor' '409': description: Idempotency Error content: application/json: schema: $ref: '#/components/schemas/Error409' '422': description: Unprocessable Entity content: application/json: schema: properties: status: type: boolean example: false message: type: string example: The given data was invalid. data: type: object example: null errors: $ref: '#/components/schemas/BusinessValidationError' error_code: type: string example: null type: object '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - ApiToken: [] components: schemas: Business: required: - name - tin - address properties: name: type: string example: John Incorporation tin: type: string example: '123456789' transaction_fee_percent: type: number format: float example: 2.5 transaction_fee_fixed: type: number format: integer example: 100 maximum_transaction_fee: type: number format: integer example: 1000 payout_type: type: string enum: - batch - individual example: individual nullable: true trading_name: type: string example: John Incorporation entity_type: type: string example: Sole Trader incorporation_date: type: string example: '2024-02-02' incorporation_state: type: string example: CO industry: type: string example: Nature of business industry_classification: properties: code_type: type: string example: SIC codes: type: array items: type: string example: NAICS 42 description: type: string example: abcdefg type: object source_of_wealth: type: string example: '2344' source_of_funds: type: string example: skjdkd first_transaction_completed_at: type: string example: '2024-05-02 16:14:25' product_type: type: string example: financial registered_as_inactive: type: boolean example: false address_type: type: string example: Registered address: $ref: '#/components/schemas/Address' type: object BusinessOwner: required: - first_name - last_name - dob - ssn9 - address - email - phone properties: first_name: type: string example: John last_name: type: string example: Dew dob: type: string example: '2023-04-11' ssn9: type: string example: '123456789' address: $ref: '#/components/schemas/Address' is_beneficial_owner: type: boolean example: true is_director: type: boolean example: false is_account_owner: type: boolean example: false is_share_holder: type: boolean example: false is_significant_control_person: type: boolean example: false ownership_percentage: type: number format: float example: 25 email: type: string example: '[email protected]' phone: type: string example: '2457856490' occupation: type: string example: Co-founder first_transaction_completed_at: type: string example: '2024-05-02 16:14:25' product_type: type: string example: financial type: object V2BankAccountRequest: description: Bank account can be either Plaid or Custom, not both oneOf: - required: - custom properties: custom: $ref: '#/components/schemas/CustomBankAccount' type: object - required: - plaid properties: plaid: $ref: '#/components/schemas/PlaidAccount' type: object V2OnboardBusinessResponse: title: Business Response description: Schema for a Business response properties: status: description: Response status type: boolean example: true message: description: Response message type: string data: description: Business data properties: client_reference_id: type: string example: company_45458 uuid: type: string example: 9d264b4a-006c-4d01-acd0-730e27784c59 first_name: type: string example: John last_name: type: string example: Dew email: type: string example: john.dew@example.com phone: type: string example: '2457856490' business: properties: name: type: string example: John Incorporation tin: type: string example: '922454715' address_type: type: string example: Registered address: properties: street_address: type: string example: 10554 W Quarles Ave additional_address: type: string example: Suite 123 city: type: string example: Littleton state: type: string example: CO country: type: string example: US zip: type: string example: '80127' type: object trading_name: type: string example: John Incorporation entity_type: type: string example: Sole Trader incorporation_date: type: string format: date example: '2024-02-02' incorporation_state: type: string example: CO industry: type: string example: Nature of business industry_classification: properties: code_type: type: string example: SIC codes: type: array items: type: string example: - NAICS 42 - NAICS 45 description: type: string example: NAICS type: object source_of_wealth: type: string example: '2344' source_of_funds: type: string example: Industry first_transaction_completed_at: type: string format: date-time example: '2024-05-02 16:14:25' product_type: type: string example: financial registered_as_inactive: type: boolean example: false transaction_fee_percent: type: number format: float example: 2.5 nullable: true transaction_fee_fixed: type: integer example: 100 nullable: true maximum_transaction_fee: type: integer example: 1000 nullable: true type: object user_status: type: string example: APPROVED kyb_status: type: string example: APPROVED kyb_rejected_reason: type: string example: null nullable: true financing_credit_balance: type: number format: float example: null nullable: true payout_type: type: string example: batch role: type: string example: business vendor_name: type: string example: Fintech business_owners: type: array items: properties: first_name: type: string example: John last_name: type: string example: Dew dob: type: string format: date example: '2023-04-11' ssn9: type: string example: '123456789' address_line_1: type: string example: 10554 W Quarles Ave address_line_2: type: string example: Suite 123 city: type: string example: Littleton state: type: string example: CO zip: type: string example: '80127' is_beneficial_owner: type: boolean example: true is_director: type: boolean example: false is_account_owner: type: boolean example: false is_share_holder: type: boolean example: false is_significant_control_person: type: boolean example: false ownership_percentage: type: number format: float example: 25 email: type: string example: john.dew@example.com phone: type: string example: '2457856490' nationality: type: string example: US occupation: type: string example: Co-founder first_transaction_completed_at: type: string format: date-time example: '2024-05-02 16:14:25' product_type: type: string example: financial type: object valid_account: type: string example: Valid bank_account: properties: risk: properties: confidence_score: type: number format: float example: '0.83' nullable: true threshold: type: number format: float example: '0.61' nullable: true type: object type: object created_at: type: string format: date-time example: '2024-10-02 14:06:14' updated_at: type: string format: date-time example: '2024-10-02 14:06:17' type: object errors: description: Error details if any type: object nullable: true error_code: description: Error code if any type: string nullable: true type: object Error400: properties: status: type: boolean example: false message: type: string example: Invalid Parameters Received data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error400InvalidAcceptHeader: properties: status: type: boolean example: false message: type: string example: Invalid value provided for Accept header. data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error400InvalidPlaidAccount: properties: status: type: boolean example: false message: type: string example: Invalid plaid account ID or access token. data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error400UnverifiedPlaidAccount: properties: status: type: boolean example: false message: type: string example: Plaid account ID couldn't be verified. data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error400InvalidRoutingNumber: properties: status: type: boolean example: false message: type: string example: 'Invalid routing_number: 000000000. This routing number is invalid.' data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error401Unauthorized: properties: status: type: boolean example: false message: type: string example: Invalid Token data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error401UnauthorizedProcessor: properties: status: type: boolean example: false message: type: string example: This action is unauthorized. data: type: string example: null errors: type: string example: null error_code: type: string example: null type: object Error409: properties: status: type: boolean example: false message: type: string example: >- The request cannot be executed due to a detected conflict with a duplicate request. data: type: string example: null errors: type: string example: null error_code: type: string example: server_error type: object BusinessValidationError: properties: kyb: type: object example: - The kyb field must be true or false. client_reference_id: type: object example: - The Client reference id must be a string. - The Client reference id may not be greater than 255 characters. payout_type: type: object example: - The payout type must be a string. - The payout type should be either individual or batch. first_name: type: object example: - The First name must be a string. - The first name may not be greater than 56 characters. - The First name field is required. last_name: type: object example: - The Last name must be a string. - The last name may not be greater than 56 characters. - The Last name field is required. email: type: object example: - The Email must be a valid email address. - The Email field is required. phone: type: object example: - The Phone must be a string. - >- Phone numbers should consist of 10 digits and should not contain the +1 prefix or any special characters. - The Phone field is required. business: type: object example: - The business field is required. business.name: type: object example: - The Business name must be a string. - The Business name may not be greater than 64 characters. - The Business name field is required. business.tin: type: object example: - The Tin number must be a string. - The Tin number must consist of 9 digit. - The Tin number field is required. business.trading_name: type: object example: - The Business trading name must be a string. - The Business trading name field is required. business.entity_type: type: object example: - The Entity type must be a string. - The Entity type field is required. business.incorporation_date: type: object example: - The Incorporation date is not a valid date. - The Incorporation date does not match the format Y-m-d. - The Incorporation date field is required. business.incorporation_state: type: object example: - The Incorporation state must be a string. - The Incorporation state must be valid US state. - The Incorporation state field is required. business.industry: type: object example: - The Industry must be a string. business.industry_classification.code_type: type: object example: - The Industry classification code type must be a string. - >- The Industry classification code type is required when industry classification is present. business.industry_classification.codes: type: object example: - >- The Industry classification codes is required when industry classification is present. - The business.industry_classification.codes.0 must be a string. business.industry_classification.description: type: object example: - The Industry classification description must be a string. - >- The Industry classification description is required when industry classification is present. business.source_of_wealth: type: object example: - The Source of wealth must be a string. business.first_transaction_completed_at: type: object example: - >- The First transaction completed date does not match the format Y-m-d H:i:s. - The First transaction completed date must be a date before now. business.address_type: type: object example: - The Address type must be a string. - The Address type field is required. business.address: type: object example: - The business.address field is required. business.address.line_1: type: object example: - The Business address line 1 must be a string. - The Business address line 1 field is required. business.address.line_2: type: object example: - The Business address line 2 must be a string. business.address.city: type: object example: - The Business city name must be a string. - The Business city name may not be greater than 56 characters. - The Business city name field is required. - >- The Business city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces. business.address.state: type: object example: - The Business state name must be a string. - The Business state name may not be greater than 2 characters. - The Business state name must be valid US state. - The Business state name field is required. business.address.zip: type: object example: - The Business zip code must be a string. - The Business zip code must consist of 5 digit. - The Business zip code field is required. business.transaction_fee_percent: type: object example: - The Transaction fee percent must be a number. - The Transaction fee percent may not be greater than 99.99. - The Transaction fee percent must be at least 0. business.maximum_transaction_fee: type: object example: - The business maximum transaction fee must be an integer. - The business maximum transaction fee must be at least 0. business.transaction_fee_fixed: type: object example: - The business transaction fee fixed must be an integer. - The business transaction fee fixed must be at least 0. bank_account.plaid: type: object example: - If a bank account exists, Plaid should not be presented. - The Plaid account id and access token is required. bank_account.plaid.access_token: type: object example: - The Plaid access token is required when plaid is present. - The Plaid access token must be a string. bank_account.plaid.account_id: type: object example: - The Plaid account id is required when plaid is present. - The Plaid account id must be a string. bank_account.custom: type: object example: - 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: type: object example: - The Bank account number must be a string. - The Bank account number may not be greater than 17 characters. - The Bank account number is required when bank account is present. bank_account.custom.routing_number: type: object example: - The Bank routing number must be a number. - The Bank routing number must consist of 9 digit - The Bank routing number is required when bank account is present. bank_account.custom.account_name: type: object example: - The Bank account name must be a string. - The Bank account name is required when bank account is present. bank_account.custom.account_type: type: object example: - The Bank account type must be a string. - The Bank account type should be either savings or checking. - The Bank account type is required when bank account is present. bank_account.custom.validate_account_routing: type: object example: - >- The Validate account and routing number field must be true or false. billing_merchant_user_uuid: type: object example: - The requested billing merchant user uuid does not exist. - The Billing Merchant User UUID must be a valid UUID. - >- The billing merchant is deleted and cannot be used for billing purposes. billing_processor_mid: type: object example: - The requested billing processor MID does not exist. - >- The billing processor MID is deleted and cannot be used for billing purposes. business_owners: type: object example: - The Business owners field is required. - The number of Business owners should not exceed 5 business_owners.0.first_name: type: object example: - The Business owner first name must be a string. - >- The Business owner first name may not be greater than 56 characters. - The Business owner first name field is required. business_owners.0.last_name: type: object example: - The Business owner last name must be a string. - >- The Business owner last name may not be greater than 56 characters. - The Business owner last name field is required. business_owners.0.email: type: object example: - The Business owner email must be a valid email address. - The Business owner email field is required. business_owners.0.phone: type: object example: - The Business owner phone must be a string. - >- The Business owner phone should consist of 10 digits without the +1 prefix. - The Business owner phone field is required. business_owners.0.dob: type: object example: - The Business owner date of birth does not match the format Y-m-d. - The Business owner date of birth field is required. business_owners.0.ssn9: type: object example: - The Business owner SSN must be a string. - The Business owner SSN must consist of 9 digit. - The Business owner SSN field is required. business_owners.0.address.line_1: type: object example: - The Business owner address line 1 must be a string. - The Business owner address line 1 field is required. business_owners.0.address.line_2: type: object example: - The Business owner address line 2 must be a string. business_owners.0.address.city: type: object example: - The Business owner city name must be a string. - >- The Business owner city name may not be greater than 56 characters. - >- The Business owner city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces. - The Business owner city name field is required. business_owners.0.address.state: type: object example: - The Business owner state name must be a string. - >- The Business owner state name may not be greater than 2 characters. - The Business owner state name must be valid US state. - The Business owner state name field is required. business_owners.0.address.zip: type: object example: - The Business owner zip code must be a string. - The Business owner zip code must consist of 5 digit. - The Business owner zip code field is required. business_owners.0.is_beneficial_owner: type: object example: - >- The Business owner is beneficial owner field must be true or false. business_owners.0.is_director: type: object example: - The Business owner is director field must be true or false. business_owners.0.is_account_owner: type: object example: - The Business owner is account owner field must be true or false. business_owners.0.is_share_holder: type: object example: - The Business owner is share holder field must be true or false. business_owners.0.is_significant_control_person: type: object example: - >- The Business owner is significant control person field must be true or false. business_owners.0.occupation: type: object example: - The Business owner occupation must be a string. business_owners.0.ownership_percentage: type: object example: - The Business owner ownership percentage must be a number. - The Business owner ownership percentage must be between 0 and 100. business_owners.0.first_transaction_completed_at: type: object example: - >- The Business owner first transaction completed date does not match the format Y-m-d H:i:s. - >- The Business owner first transaction completed date must be a date before now. business_owners.0.product_type: type: object example: - The Business owner product type must be a string. business_owners.0.registered_as_inactive: type: object example: - The Registered as inactive field must be true or false. type: object Error500: properties: status: type: boolean example: false message: type: string example: Internal server error occurred. data: type: string example: null errors: type: string example: null error_code: type: string example: server_error type: object Address: required: - line_1 - city - state - zip properties: line_1: type: string example: 10554 W Quarles Ave line_2: type: string example: Suite 123 city: type: string example: Littleton state: type: string example: CO zip: type: string example: '80127' type: object CustomBankAccount: required: - account_number - routing_number - account_name - account_type properties: account_number: type: string example: '123456789' routing_number: type: string example: '123456789' account_name: type: string example: John Doe account_type: type: string example: checking type: object PlaidAccount: required: - account_id - access_token properties: account_id: type: string example: '123456789' access_token: type: string example: token123 type: object securitySchemes: ApiToken: type: http description: >- Token-based authentication using Authorization: Bearer provided by the GrailPay Support Team. bearerFormat: Token scheme: bearer ````