> ## 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. # Add a new bank account to a person. ( STABLE ) > This endpoint allows for adding a new Bank Account to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object. 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/people/{uuid}/bank-accounts 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/people/{uuid}/bank-accounts: post: tags: - Bank Accounts - Stable summary: Add a new bank account to a person. ( STABLE ) description: >- This endpoint allows for adding a new Bank Account to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object. When including the bank account, you can pass either Plaid information or account and routing information. You should never pass both. operationId: 382621bd16dd23255f6fb5245235a0cd parameters: - name: uuid in: path description: UUID of the person required: true schema: type: string format: uuid example: 7c41f6a2-a4b9-4df8-9225-2c1b7312042e requestBody: required: true content: application/json: schema: properties: person: properties: first_name: type: string example: John last_name: type: string example: Doe type: object billing_merchant_uuid: type: string format: uuid example: 6a8fc154-1a50-483b-a690-fd1dfaf9408b billing_processor_mid: type: string example: '12345678' bank_account: $ref: '#/components/schemas/V3BankAccountObject' actions: properties: account_intelligence: $ref: '#/components/schemas/V3AccountIntelligenceRequestObject' type: object type: object responses: '200': description: The response returned from a successful call to add a bank account. content: application/json: schema: properties: status: type: boolean example: true message: type: string example: >- This bank account already exists for this person. We have attached it as the default bank account. data: properties: bank_account: $ref: '#/components/schemas/V3BankAccountResponse' 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 '201': description: The response returned from a successful call to add a bank account. content: application/json: schema: properties: status: type: boolean example: true message: type: string example: The bank account was created and attached successfully. data: properties: bank_account: $ref: '#/components/schemas/V3BankAccountResponse' 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' '403': description: 403 - Forbidden content: application/json: schema: properties: status: type: boolean example: false message: type: string oneOf: - example: >- This person is not available as they have been scheduled for deletion. - example: >- This person is currently on hold and is unable to be modified. 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 '404': description: 404 - Not Found content: application/json: schema: properties: status: type: boolean example: false message: type: string example: No person was found matching that UUID. 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 '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: 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. 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. bank_account: type: object example: - The bank account field is required. - >- 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 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: Something went wrong on our side. Please contact support. 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: 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 V3BankAccountResponse: properties: aggregator_type: type: string example: manual uuid: type: string format: uuid example: 9b97f121-a449-4b52-9f36-6c55f18394d6 is_default: type: boolean example: true account_number: type: string example: '********1234' routing_number: type: string example: '*****6789' account_name: type: string example: John Doe account_type: type: string example: checking 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 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 ````