1. Use Case 3: Manage Taxpayers
  2. Use Case 3: Manage Taxpayers

Synchronize taxpayer data between your system and Remitian. Create, list, deactivate, and change the owner of taxpayers associated with firms using your system’s taxpayer ID with the externalId field, or find them by TIN with encryptedTin.

Use Case 3: Manage Taxpayers

​
Understanding Taxpayers

Taxpayers represent a container for tax entities and tax accounts within the Remitian system. Once created, you can add tax entities (e.g., individuals, businesses), schedule tax payments, and import tax forms.

Taxpayer Object Structure:

FieldTypeDescription
taxpayerIdguidUnique identifier for the taxpayer
Example: 029bc3f4-d65e-73f7-8133-f5800e825510
externalIdstringYour system’s unique identifier
Example: my_taxpayer_123
businessIdstringUser interface friendly identifier
Example: TP-654321
namestringName of the taxpayer
Example: John Doe
userIdguidUnique identifier for the associated user, returned in the create response
Example: 049bc3f4-d65e-73f7-8133-f5800e825512
taxpayerUserObjectInformation about the taxpayer user

​
Create Taxpayers

There are two ways to create a taxpayer, both described in Provision and Create Taxpayers:


​
List Taxpayers

Sequence of Events:

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

Query Parameters:

ParameterTypeDescription
externalIdstringFilter by your system’s taxpayer ID
Example: my_taxpayer_123
emailAddressstringFilter by the taxpayer user’s email address. Exact match, case-insensitive
Example: john.doe@acme.com
encryptedTinstringFilter by the TIN of the taxpayer’s tax entities, exact match. The TIN encrypted with the Remitian public key, base64url without padding. An empty value is ignored and does not filter. See Find Taxpayers by TIN below
pageNumbernumberPage to retrieve
Example: 1
pageSizenumberItems per page
Example: 10

HTTP Request:

GET https://public-api.remitian.com/v1/firms/{firmId}/taxpayers?emailAddress=john.doe@acme.com
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

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

{
  "items": [
    {
      "id": "029bc3f4-d65e-73f7-8133-f5800e825510",
      "externalId": "my_taxpayer_123",
      "businessId": "TP-654321",
      "name": "John Doe",
      "taxpayerUser": {
        "id": "039bc3f4-d65e-73f7-8133-f5800e825511",
        "user": {
          "id": "049bc3f4-d65e-73f7-8133-f5800e825512",
          "businessId": "UR-789012",
          "name": "John",
          "lastName": "Doe",
          "fullName": "John Doe",
          "emailAddress": "john.doe@acme.com",
          "isActive": true,
          "inviteStatus": "Accepted"
        }
      }
    }
  ],
  "currentPage": 1,
  "pageSize": 10,
  "totalCount": 1,
  "totalPages": 1
}

When filters are combined, only taxpayers matching all of them are returned.


​
Find Taxpayers by TIN

The TIN belongs to the tax entity, not to the taxpayer. To find the taxpayers that own a tax entity with a given TIN, without listing the tax entities of each taxpayer, send the encrypted TIN in encryptedTin when listing taxpayers.

Sequence of Events:

  1. Your system encrypts the TIN (SSN, ITIN or EIN, 9 digits without hyphens) with the Remitian TIN encryption public key, as described in Filter Tax Entities by TIN
  2. Your system sends the list request with the encrypted value in encryptedTin
  3. Remitian decrypts it and responds with the taxpayers of the firm that own a tax entity with that TIN

HTTP Request:

GET https://public-api.remitian.com/v1/firms/{firmId}/taxpayers?encryptedTin={encryptedTin}
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

The response has the same format as List Taxpayers. A taxpayer cannot have two tax entities with the same TIN, but the same TIN can belong to tax entities of different taxpayers, so the list can have more than one taxpayer. Each taxpayer appears once. Only taxpayers of the firm in the path are returned; no match returns an empty list.

Errors:

The errors are the same as in Filter Tax Entities by TIN: a value that cannot be decoded or decrypted, or a decrypted TIN in an invalid format, returns 400 Bad Request with the TaxEntity.InvalidEncryptedTin error, and an environment without TIN encryption returns 404 Not Found. The response never repeats the value sent.


​
Deactivate a Taxpayer

Sequence of Events:

  1. Your system sends a request to deactivate a taxpayer using the taxpayerId
  2. Remitian responds with a confirmation of the deactivation

HTTP Request:

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

HTTP Response:

HTTP/1.1 204 No Content

​
Change the Owner of a Taxpayer

Sequence of Events:

  1. Your system sends a request with the ownerFirmUserId of the new owner, using the firmId and the taxpayerId
  2. Remitian responds with a confirmation of the change

HTTP Request:

POST https://public-api.remitian.com/v1/firms/{firmId}/taxpayers/{taxpayerId}/change-owner-firm-user
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "ownerFirmUserId": "029bc3f4-d65e-73f7-8133-f5800e825510"
}

Note: The new owner must be allowed to own clients: either an Admin, or an Accountant/TeamMember created with CanOwnClients in optionalPermissions (see Use Case 2). Otherwise the request fails with 403 Forbidden and the message Owner user does not have permission to own clients. The new owner does not need to be active or to have accepted its invite.

HTTP Response:

HTTP/1.1 204 No Content