1. Use Case 4: Manage Tax Entities
  2. Use Case 4: Manage Tax Entities

Manage tax entities associated with taxpayers. Create and list tax entities using your system’s tax entity ID with the externalId field, or find them by TIN with encryptedTin. Each tax entity must be associated with an existing taxpayer.

Use Case 4: Manage Tax Entities

​
Understanding Tax Entities

Tax entities represent individuals or businesses that have tax accounts. Once created, you can add tax accounts for them and schedule tax payments.

Available Tax Entity Types:

  • IrsSsn - Individual with Social Security Number
  • IrsEin - Business with Employer Identification Number

Individual Tax Entity Object Structure:

FieldTypeDescription
idguidUnique identifier for the tax entity
Example: 039bc3f4-d65e-73f7-8133-f5800e825511
externalIdstringYour system’s unique identifier
Example: my_individual_entity_123
typestringType of the tax entity
Example: IrsSsn
tinstringTax Identification Number, 9 digits without hyphens. Masked in responses for individual tax entities, showing only the last 2 digits
Example: *******89
firstNamestringFirst name
Example: Alice
lastNamestringLast name
Example: Smith
addressAddress(Optional) Address details, for individual and business tax entities. When sent, city, region, country and postalCode are required (postalCode with 5 digits for US). A request that breaks these rules is rejected with 400 Bad Request. Some tax payments depend on it, so send it whenever you have it. Returned as null when the tax entity has no address

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


​
Create an Individual Tax Entity

Sequence of Events:

  1. Your system sends a request to create a tax entity using an external ID and associates it with an existing taxpayer
  2. Remitian responds with the created tax entity’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-entities
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_individual_entity_123",
  "type": "IrsSsn",
  "tin": "123456789",
  "firstName": "Alice",
  "lastName": "Smith",
  "address": {
    "address1": "123 Main St",
    "address2": "Suite 4B",
    "city": "Springfield",
    "region": "IL",
    "country": "US",
    "postalCode": "62701"
  }
}

HTTP Response:

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

{
  "id": "039bc3f4-d65e-73f7-8133-f5800e825511",
  "externalId": "my_individual_entity_123"
}

​
Create a Business Tax Entity

Sequence of Events:

  1. Your system sends a request to create a business tax entity using an external ID
  2. Remitian responds with the created business tax entity’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-entities
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_business_entity_456",
  "type": "IrsEin",
  "tin": "123456789",
  "businessName": "Acme Corporation",
  "address": {
    "address1": "456 Corporate Blvd",
    "address2": "Floor 10",
    "city": "Metropolis",
    "region": "NY",
    "country": "US",
    "postalCode": "10001"
  }
}

HTTP Response:

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

{
  "id": "049bc3f4-d65e-73f7-8133-f5800e825512",
  "externalId": "my_business_entity_456"
}

​
List Tax Entities

Sequence of Events:

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

Query Parameters:

ParameterTypeDescription
externalIdstringFilter by your system’s tax entity ID
Example: my_individual_entity_123
encryptedTinstringFilter by exact TIN match. The TIN encrypted with the Remitian public key, base64url without padding. See Filter Tax Entities by TIN. The response format of the TIN does not change
pageNumbernumberPage to retrieve
Example: 1
pageSizenumberItems per page
Example: 10

When externalId and encryptedTin are combined, only tax entities matching both are returned.

HTTP Request:

GET https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-entities
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

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

{
  "items": [
    {
      "id": "039bc3f4-d65e-73f7-8133-f5800e825511",
      "externalId": "my_individual_entity_123",
      "type": "IrsSsn",
      "tin": "*******89",
      "firstName": "Alice",
      "lastName": "Smith",
      "address": {
        "address1": "123 Main St",
        "address2": "Suite 4B",
        "city": "Springfield",
        "region": "IL",
        "country": "US",
        "postalCode": "62701"
      }
    },
    {
      "id": "049bc3f4-d65e-73f7-8133-f5800e825512",
      "externalId": "my_business_entity_456",
      "type": "IrsEin",
      "tin": "123456789",
      "businessName": "Acme Corporation",
      "address": {
        "address1": "456 Corporate Blvd",
        "address2": "Floor 10",
        "city": "Metropolis",
        "region": "NY",
        "country": "US",
        "postalCode": "10001"
      }
    }
  ],
  "currentPage": 1,
  "pageSize": 10,
  "totalCount": 2,
  "totalPages": 1
}

​
Filter by TIN

The TIN is sensitive data: Remitian never accepts it in plaintext in a URL. To find a tax entity by TIN, encrypt the TIN with the Remitian public key and send it in the encryptedTin filter of the tax entity list.

See Filter Tax Entities by TIN for the encryption parameters, code examples, errors and key rotation.


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


​
Next Steps

Once a tax entity exists, you can create tax accounts for it (see Use Case 5) and manage its tax identity verifications with tax authorities (see Use Case 6: Manage Tax Identity Verifications).