- Use Cases
- Use Case 7: Manage Bank Accounts
Use Cases
Use Case 7: Manage Bank Accounts
Create, list, and delete ACH and EFT bank accounts for taxpayers, and register firm bank accounts.
Manage bank accounts associated with taxpayers or firms. Create, list, and delete bank accounts using your system’s bank account ID with the externalId field. Each bank account belongs to exactly one owner: an existing taxpayer or an existing firm.

Understanding Bank Accounts
Bank accounts represent the funding sources used to pay tax obligations for a taxpayer. Once created, a bank account can be associated with tax payments so Remitian can process them on the scheduled date.
Bank accounts are polymorphic and keyed on the paymentNetwork field:
Available Payment Networks:
Ach- US ACH transfer. RequiresroutingNumber.Eft- Canadian EFT transfer. RequiresinstitutionNumberandtransitNumber.
Bank Account Object Structure:
| Field | Type | Description |
|---|---|---|
id | guid | Unique identifier for the bank account Example: 079bc3f4-d65e-73f7-8133-f5800e825515 |
externalId | string | Your system’s unique identifier (optional) Example: my_bank_account_123 |
taxpayerId | guid | Associated taxpayer identifier Example: 029bc3f4-d65e-73f7-8133-f5800e825510 |
bankAccountName | string | Name of the bank account Example: Business Checking |
accountNumber | string | Bank account number Example: 000123456789 |
paymentNetwork | string | Payment network Example: Ach, Eft |
routingNumber | string | Routing number (ACH only) Example: 021000021 |
institutionNumber | string | Institution number (EFT only) Example: 001 |
transitNumber | string | Transit number (EFT only) Example: 12345 |
isPlaidConnected | boolean | Whether the bank account was connected through Plaid Example: true |
institutionName | string | Name of the bank returned by Plaid (optional). Not returned for bank accounts entered manually, for Plaid bank accounts connected before this field was available, or when Plaid did not return the bank’s name Example: Chase |
Create a Bank Account
Sequence of Events:
- Your system sends a request to create a bank account using an external ID and associates it with an existing taxpayer
- The request body varies by
paymentNetwork— provideroutingNumberforAch, orinstitutionNumberandtransitNumberforEft - Remitian responds with the created bank account’s details
- Your system can then use this
idfor subsequent operations
HTTP Request (ACH):
POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
{
"externalId": "my_ach_account_123",
"paymentNetwork": "Ach",
"bankAccountName": "Business Checking",
"accountNumber": "000123456789",
"routingNumber": "021000021"
}
HTTP Request (EFT):
POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
{
"externalId": "my_eft_account_456",
"paymentNetwork": "Eft",
"bankAccountName": "Operating Account",
"accountNumber": "1234567",
"institutionNumber": "001",
"transitNumber": "12345"
}
HTTP Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825515",
"externalId": "my_ach_account_123"
}
List Bank Accounts
Sequence of Events:
- Your system sends a request to list all bank accounts associated with a specific taxpayer
- You can filter bank accounts by
externalIdand page the results withpageNumberandpageSize - Remitian responds with a paginated list of bank accounts
HTTP Request:
GET https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts?externalId=my_ach_account_123&pageNumber=1&pageSize=50
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
HTTP Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"items": [
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825515",
"externalId": "my_ach_account_123",
"taxpayerId": "029bc3f4-d65e-73f7-8133-f5800e825510",
"bankAccountName": "Business Checking",
"accountNumber": "000123456789",
"paymentNetwork": "Ach",
"routingNumber": "021000021",
"isPlaidConnected": true,
"institutionName": "Chase"
},
{
"id": "089bc3f4-d65e-73f7-8133-f5800e825516",
"externalId": "my_eft_account_456",
"taxpayerId": "029bc3f4-d65e-73f7-8133-f5800e825510",
"bankAccountName": "Operating Account",
"accountNumber": "1234567",
"paymentNetwork": "Eft",
"institutionNumber": "001",
"transitNumber": "12345",
"isPlaidConnected": false
}
],
"currentPage": 1,
"pageSize": 50,
"totalCount": 2,
"totalPages": 1
}
Delete a Bank Account
Sequence of Events:
- Your system sends a request to delete a specific bank account associated with a taxpayer
- Remitian removes the bank account and responds with no content
- If the bank account does not exist for the taxpayer, Remitian responds with
404 Not Found
HTTP Request:
DELETE https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts/{bankAccountId}
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
HTTP Response:
HTTP/1.1 204 No Content
Firm Bank Accounts
A firm can register its own bank account, separate from the bank accounts of its taxpayers. Firm bank accounts are ACH only, and are identified on incoming credits by the optional fundingCompanyId.
Firm Bank Account Object Structure:
| Field | Type | Description |
|---|---|---|
id | guid | Unique identifier for the bank account Example: 079bc3f4-d65e-73f7-8133-f5800e825517 |
externalId | string | Your system’s unique identifier (optional) Example: my_firm_account_789 |
firmId | guid | Associated firm identifier Example: 019bc3f4-d65e-73f7-8133-f5800e825501 |
bankAccountName | string | Name of the bank account Example: Firm Operating Account |
accountNumber | string | Bank account number Example: 000987654321 |
paymentNetwork | string | Payment network, always Ach |
routingNumber | string | 9-digit routing number Example: 021000021 |
fundingCompanyId | string | ACH Company ID the firm originates its credits from (optional, up to 50 characters). Unique across all bank accounts Example: 1234567890 |
Create a Firm Bank Account
Sequence of Events:
- Your system sends a request to create a bank account for an existing firm
- Remitian responds with the created bank account’s details
- If the firm already has a bank account with the same routing and account number, or the
fundingCompanyIdis already registered to another bank account, Remitian responds with409 Conflict - If the firm does not exist, Remitian responds with
404 Not Found
HTTP Request:
POST https://public-api.remitian.com/v1/firms/{firmId}/bank-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
{
"externalId": "my_firm_account_789",
"bankAccountName": "Firm Operating Account",
"accountNumber": "000987654321",
"routingNumber": "021000021",
"fundingCompanyId": "1234567890"
}
HTTP Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825517",
"externalId": "my_firm_account_789"
}
List Firm Bank Accounts
Sequence of Events:
- Your system sends a request to list the bank accounts of a specific firm
- You can page the results with
pageNumberandpageSize - Remitian responds with a paginated list of the firm’s bank accounts. Bank accounts of the firm’s taxpayers are not included
HTTP Request:
GET https://public-api.remitian.com/v1/firms/{firmId}/bank-accounts?pageNumber=1&pageSize=50
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
HTTP Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"items": [
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825517",
"externalId": "my_firm_account_789",
"firmId": "019bc3f4-d65e-73f7-8133-f5800e825501",
"bankAccountName": "Firm Operating Account",
"accountNumber": "000987654321",
"paymentNetwork": "Ach",
"routingNumber": "021000021",
"fundingCompanyId": "1234567890"
}
],
"currentPage": 1,
"pageSize": 50,
"totalCount": 1,
"totalPages": 1
}