1. Use Cases
  2. Use Case 5: Manage Tax Accounts

Manage tax accounts associated with tax entities. Create and list tax accounts using your system’s tax account ID with the externalId field. Each tax account must be associated with an existing tax entity.

Use Case 5: Manage Tax Accounts

​
Understanding Tax Accounts

Tax accounts represent specific tax obligations (e.g., federal, state) for a tax entity. For one tax entity, you can create multiple tax accounts for different tax authorities. Once created, you can schedule tax payments for them.

Available Tax Account Types:

  • Personal
  • Corporate

Available Tax Authorities:

  • US_IRS - Internal Revenue Service
  • US_GA - Georgia Department of Revenue
  • US_CA - California Franchise Tax Board
  • US_DC - District of Columbia Office of Tax and Revenue
  • US_WI - Wisconsin Department of Revenue
  • US_CO - Colorado Department of Revenue
  • US_AZ - Arizona Department of Revenue
  • US_MA - Massachusetts Department of Revenue
  • US_NC - North Carolina Department of Revenue
  • US_VA - Virginia Department of Taxation
  • US_NJ - New Jersey Division of Taxation
  • US_FL - Florida Department of Revenue
  • US_IL - Illinois Department of Revenue
  • US_PA - Pennsylvania Department of Revenue
  • US_MD - Comptroller of Maryland
  • US_TX - Texas Comptroller of Public Accounts
  • US_OH - Ohio Department of Taxation
  • US_SC - South Carolina Department of Revenue
  • US_DE - Delaware Division of Revenue
  • US_UT - Utah State Tax Commission
  • US_VT - Vermont Department of Taxes
  • US_KY - Kentucky Department of Revenue
  • US_MI - Michigan Department of Treasury
  • US_MO - Missouri Department of Revenue
  • US_OK - Oklahoma Tax Commission
  • US_NM - New Mexico Taxation and Revenue Department
  • US_OR - Oregon Department of Revenue
  • US_PA_PHI - Philadelphia Department of Revenue
  • US_TN - Tennessee Department of Revenue
  • US_AR - Arkansas Department of Finance and Administration
  • US_ID - Idaho State Tax Commission
  • US_IN - Indiana Department of Revenue
  • US_AL - Alabama Department of Revenue
  • US_HI - Hawaii Department of Taxation
  • US_KS - Kansas Department of Revenue
  • US_CT - Connecticut Department of Revenue Services
  • US_ND - North Dakota Office of State Tax Commissioner
  • US_LA - Louisiana Department of Revenue
  • US_ME - Maine Revenue Services
  • US_IA - Iowa Department of Revenue
  • US_MN - Minnesota Department of Revenue
  • US_WV - West Virginia Tax Division
  • US_NY - New York State Department of Taxation and Finance
  • US_NYC - New York City Department of Finance
  • US_MS - Mississippi Department of Revenue
  • US_MT - Montana Department of Revenue
  • US_NE - Nebraska Department of Revenue

Tax Account Object Structure:

FieldTypeDescription
idguidUnique identifier for the tax account
Example: 059bc3f4-d65e-73f7-8133-f5800e825513
externalIdstringYour system’s unique identifier
Example: my_tax_account_123
taxEntityIdguidAssociated tax entity identifier
Example: 039bc3f4-d65e-73f7-8133-f5800e825511
typestringType of the tax account
Example: Personal, Corporate
taxAuthoritystringTax authority
Example: US_IRS, US_GA

externalId must be 3 to 100 characters long and contain only letters, numbers, spaces, underscores, commas, periods or hyphens.


​
Create a Tax Account

Sequence of Events:

  1. Your system sends a request to create a tax account using an external ID and associates it with an existing tax entity
  2. Remitian responds with the created tax account’s details
  3. Your system can then use this id for subsequent operations

HTTP Request:

POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_tax_account_123",
  "taxEntityId": "039bc3f4-d65e-73f7-8133-f5800e825511",
  "type": "Personal",
  "taxAuthority": "US_IRS"
}

HTTP Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "059bc3f4-d65e-73f7-8133-f5800e825513",
  "externalId": "my_tax_account_123"
}

​
List Tax Accounts

Sequence of Events:

  1. Your system sends a request to list all tax accounts associated with a specific taxpayer
  2. You can filter tax accounts by externalId if needed
  3. Remitian responds with a paginated list of tax accounts

HTTP Request:

GET https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-accounts?externalId=my_tax_account_123
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "059bc3f4-d65e-73f7-8133-f5800e825513",
      "externalId": "my_tax_account_123",
      "taxEntityId": "039bc3f4-d65e-73f7-8133-f5800e825511",
      "type": "Personal",
      "taxAuthority": "US_IRS"
    }
  ],
  "currentPage": 1,
  "pageSize": 10,
  "totalCount": 1,
  "totalPages": 1
}

Tip: To create a taxpayer, its tax entities and their tax accounts in a single call, see Provision a Taxpayer.