> ## 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 into the ACH application ( STABLE ) > This endpoint allows for adding a new Business to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object, but we strongly encourage that you supply as much information as possible. When including the bank account, you can pass either Plaid information or account and routing information. You should never pass both. ## OpenAPI ````yaml https://api.grailpay.com/docs?api-docs.json post /api/v3/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: /api/v3/businesses: post: tags: - Users - Stable summary: Onboard a new Business into the ACH application ( STABLE ) description: >- This endpoint allows for adding a new Business to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object, but we strongly encourage that you supply as much information as possible. When including the bank account, you can pass either Plaid information or account and routing information. You should never pass both. operationId: 999c42d45d89d2db1aa6f3585c95a004 requestBody: required: true content: application/json: schema: properties: client_reference_id: type: string example: reference_12345 billing_merchant_uuid: type: string format: uuid example: 6a8fc154-1a50-483b-a690-fd1dfaf9408b billing_processor_mid: type: string example: '12345678' payout_type: type: string enum: - batch - individual example: batch person: $ref: '#/components/schemas/V3PersonRequestObject' business: $ref: '#/components/schemas/V3BusinessRequestObject' bank_account: $ref: '#/components/schemas/V3BankAccountObject' actions: properties: account_intelligence: $ref: '#/components/schemas/V3AccountIntelligenceRequestObject' type: object type: object responses: '201': description: The response returned from a successful call to onboard a business. content: application/json: schema: properties: status: type: boolean example: true message: type: string example: This business was onboarded successfully. data: properties: business: $ref: '#/components/schemas/V3BusinessResponseObject' relations: properties: person: properties: uuid: type: string format: uuid example: 7c41f6a2-a4b9-4df8-9225-2c1b7312042e type: object type: object account_intelligence: oneOf: - $ref: >- #/components/schemas/V3AccountIntelligenceV3Response - $ref: >- #/components/schemas/V3AccountIntelligenceV2Response - $ref: >- #/components/schemas/V3AccountIntelligenceV1Response - $ref: >- #/components/schemas/V3AccountIntelligenceThresholdResponse type: object errors: type: object example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object '400': description: 400 - Bad Request content: application/json: schema: oneOf: - $ref: '#/components/schemas/V3ErrorInvalidParameters400' - $ref: '#/components/schemas/V3ErrorInvalidAcceptHeader400' '401': description: 401 - Unauthorized content: application/json: schema: oneOf: - $ref: '#/components/schemas/V3ErrorInvalidToken401' - $ref: '#/components/schemas/V3ErrorUnauthorized401' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/V3ErrorIdempotency409' '422': description: 422 - 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 nullable: true errors: type: object allOf: - $ref: '#/components/schemas/V3OnboardingValidationErrors' - $ref: '#/components/schemas/V3PersonValidationError' - $ref: '#/components/schemas/V3BusinessValidationError' request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object '500': description: Internal Server Error content: application/json: schema: properties: status: type: boolean example: false message: type: string example: >- There was a problem on the server and the action could not be completed. Please try again. data: type: object example: null nullable: true errors: type: object example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object security: - ApiToken: [] components: schemas: V3PersonRequestObject: title: Person Request Object description: Schema for a person request object properties: first_name: type: string example: John last_name: type: string example: Doe email: type: string format: email example: john.doe@example.com phone: type: string example: '2457856490' address: $ref: '#/components/schemas/V3AddressObject' type: object V3BusinessRequestObject: title: Business Request Object description: Schema for a business request object properties: name: type: string example: Acme Inc. trading_name: type: string example: Acme Corp address: oneOf: - $ref: '#/components/schemas/V3AddressObject' nullable: true type: object V3BankAccountObject: properties: plaid_account_id: type: string nullable: true plaid_access_token: type: string nullable: true account_number: type: string example: '9876543210' routing_number: type: string example: '021000021' account_name: type: string example: John Doe account_type: type: string enum: - checking - savings example: checking type: object V3AccountIntelligenceRequestObject: required: - version properties: version: type: string enum: - v1 - v2 - v3 example: v3 name_match: type: boolean example: true nullable: true type: object V3BusinessResponseObject: properties: uuid: type: string example: a77dbb10-3686-4caf-9acd-52b3cc455db2 business_type: type: string example: business name: type: string example: Acme Inc. trading_name: type: string example: Acme Corp payout_type: type: string example: batch client_reference_id: type: string example: reference_12345 address: $ref: '#/components/schemas/V3AddressObject' timestamps: $ref: '#/components/schemas/V3TimestampsObject' type: object V3AccountIntelligenceV3Response: properties: confidence_score: type: number format: float example: 0.81 decisioning_insights: properties: account_duplicate: type: boolean example: false days_since_first_seen: type: integer example: -1 days_since_last_transaction: type: integer example: -1 has_negative_transactions: type: boolean example: false has_paid_transactions: type: boolean example: false has_positive_transactions: type: boolean example: true name_match: type: string example: 'yes' phone_number_present: type: boolean example: false valid_routing_number: type: boolean example: true type: object version: type: string example: v3 type: object V3AccountIntelligenceV2Response: properties: confidence_score: type: number format: float example: 0.81 confidence_level: type: string enum: - very low - low - medium - high - very high example: very high version: type: string example: v2 type: object V3AccountIntelligenceV1Response: properties: validity: type: string enum: - valid - invalid - not_validated example: valid version: type: string example: v1 type: object V3AccountIntelligenceThresholdResponse: properties: confidence_score: type: number format: float example: 0.81 threshold: type: number format: float example: 0.6 confidence_level: type: string enum: - very low - low - medium - high - very high example: very high version: type: string example: v2 type: object V3ErrorInvalidParameters400: properties: status: type: boolean example: false message: type: string example: Invalid Parameters Received data: type: string example: null nullable: true errors: type: string example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object V3ErrorInvalidAcceptHeader400: properties: status: type: boolean example: false message: type: string example: Invalid value provided for Accept header. data: type: object example: null nullable: true errors: type: object example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object V3ErrorInvalidToken401: properties: status: type: boolean example: false message: type: string example: Invalid token. data: type: object example: null nullable: true errors: type: object example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object V3ErrorUnauthorized401: properties: status: type: boolean example: false message: type: string example: This action is unauthorized. data: type: object example: null nullable: true errors: type: object example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object V3ErrorIdempotency409: 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: object example: null nullable: true errors: type: object example: null nullable: true request_id: type: string format: uuid example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2 type: object V3OnboardingValidationErrors: properties: 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. billing_merchant_uuid: type: object example: - The billing merchant UUID must be a valid UUID. - The billing merchant UUID does not exist. - >- The billing merchant UUID is deleted and cannot be used for billing purposes. billing_processor_mid: type: object example: - The billing processor MID must be a string. - The billing processor MID does not exist. - >- The billing processor MID is deleted and cannot be used for billing purposes. payout_type: type: object example: - The payout type must be a string. - 'The payout type must be one of the followings: individual, batch' bank_account: type: object example: - >- You cannot provide both plaid details and manual bank account fields. - >- This person did not meet the confidence score threshold of 0.5 and has been rejected. - Invalid plaid account ID or access token. - The bank routing number is not valid. bank_account.plaid_account_id: type: object example: - >- The plaid account ID is required when plaid account details is present. - The plaid account ID must be a string. bank_account.plaid_access_token: type: object example: - >- The plaid access token is required when plaid account details is present. - The plaid access token must be a string. bank_account.account_number: type: object example: - >- The bank account number is required when any manual bank account field is provided. - The bank account number must be a string. - The bank account number may not be greater than 17 characters. bank_account.routing_number: type: object example: - >- The bank routing number is required when any manual bank account field is provided. - The bank routing number must be 9 digits. bank_account.account_name: type: object example: - >- The bank account name is required when any manual bank account field is provided. - The bank account name must be a string. - The bank account name may not be greater than 255 characters. bank_account.account_type: type: object example: - >- The bank account type is required when any manual bank account field is provided. - >- The bank account type must be one of the followings: savings, checking actions.account_intelligence: type: object example: - >- The person first and last name are required when name match is true. - >- Name Match is only available when using Account Intelligence Version 3. Please update your request and try again. actions.account_intelligence.version: type: object example: - The version is required when account intelligence is present. - The version must be a string. - 'The version must be one of the followings: v1, v2, v3' actions.account_intelligence.name_match: type: object example: - The name match field must be true or false. type: object V3PersonValidationError: properties: person.first_name: type: object example: - The first name must be a string. - The first name may not be greater than 56 characters. person.last_name: type: object example: - The last name must be a string. - The last name may not be greater than 56 characters. person.email: type: object example: - The email must be a valid email address. person.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. person.address.line_1: type: object example: - The address line 1 is required when address is present. - The address line 1 must be a string. - The address line 1 may not be greater than 255 characters. person.address.line_2: type: object example: - The address line 2 must be a string. - The address line 2 may not be greater than 255 characters. person.address.city: type: object example: - The city name is required when address is present. - 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. person.address.state: type: object example: - The state is required when address is present. - The state must be a string. - The state may not be greater than 2 characters. - The state must be valid US state. person.address.zip: type: object example: - The zip code is required when address is present. - The zip code must be a string. - The zip code must consist of 5 digit. type: object V3BusinessValidationError: properties: business.name: type: object example: - The name must be a string. - The name may not be greater than 255 characters. business.trading_name: type: object example: - The trading name must be a string. - The trading name may not be greater than 255 characters. business.address.line_1: type: object example: - The address line 1 is required when address is present. - The address line 1 must be a string. - The address line 1 may not be greater than 255 characters. business.address.line_2: type: object example: - The address line 2 must be a string. - The address line 2 may not be greater than 255 characters. business.address.city: type: object example: - The city name is required when address is present. - 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. business.address.state: type: object example: - The state is required when address is present. - The state must be a string. - The state may not be greater than 2 characters. - The state must be valid US state. business.address.zip: type: object example: - The zip code is required when address is present. - The zip code must be a string. - The zip code must consist of 5 digit. type: object V3AddressObject: properties: line_1: type: string example: 10554 W Quarles Ave line_2: type: string example: Suite 123 nullable: true city: type: string example: Littleton state: type: string example: CO zip: type: string example: '80127' type: object V3TimestampsObject: properties: created_at: type: string example: '2024-06-25 13:57:03' type: object securitySchemes: ApiToken: type: http description: >- Token-based authentication using Authorization: Bearer provided by the GrailPay Support Team. bearerFormat: Token scheme: bearer ````