1. Use Case 3: Manage Taxpayers
  2. Provision and Create Taxpayers

There are two ways to create a taxpayer in a firm:

To list, deactivate or change the owner of taxpayers, see Use Case 3: Manage Taxpayers.


​
Provision a Taxpayer with Tax Entities and Tax Accounts

Provision a taxpayer, its tax entities and their tax accounts in a single call. Remitian finds each resource by its key and creates only what is missing, so it is safe to retry the same payload once the previous call has finished.

​
How Resources Are Matched

ResourceKeyScope
Taxpayeruser.emailAddressThe firm
Tax entitytinThe taxpayer
Tax accounttaxAuthority + typeThe tax entity

Rules:

  • Find or create, never update. When a resource already exists, the data sent for it is ignored and the response returns the stored data. The stored externalId can differ from the one sent.
  • externalId is optional for every resource. It is stored when the resource is created.
  • A deactivated taxpayer is not reactivated. A deactivated taxpayer matched by email is returned as Existing with status: Deactivated.

Sequence of Events:

  1. Your system sends the taxpayer, its tax entities and their tax accounts in one request
  2. Remitian validates the whole payload, then finds or creates each resource by its key in a single transaction
  3. Remitian responds with 200 OK and an outcome for each resource
  4. Your system can then use the returned ids for subsequent operations

​
Request Structure

FieldTypeDescription
taxpayerObjectThe taxpayer to find or create. Same fields as Create a Taxpayer: externalId, name, ownerFirmUserId, activate and user (emailAddress, name, lastName, phoneNumber). user.emailAddress is the lookup key, and the other fields are used only when the taxpayer is created
taxEntitiesarrayThe tax entities to find or create, at least 1. Same fields as Create an Individual Tax Entity and Create a Business Tax Entity in Use Case 4: type selects the shape, and tin is the lookup key
taxEntities[].taxAccountsarrayThe tax accounts of the tax entity, at least 1. Same fields as Create a Tax Account in Use Case 5, without taxEntityId, which comes from the parent tax entity. taxAuthority + type is the lookup key

When address is sent, address.region is required. For US addresses, address.postalCode must have 5 digits.

HTTP Request:

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

{
  "taxpayer": {
    "ownerFirmUserId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "my_taxpayer_123",
    "name": "John Doe",
    "activate": false,
    "user": {
      "emailAddress": "john.doe@acme.com",
      "name": "John",
      "lastName": "Doe",
      "phoneNumber": "+1234567890"
    }
  },
  "taxEntities": [
    {
      "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"
      },
      "taxAccounts": [
        {
          "externalId": "my_tax_account_123",
          "type": "Personal",
          "taxAuthority": "US_IRS"
        },
        {
          "externalId": "my_tax_account_124",
          "type": "Personal",
          "taxAuthority": "US_IL"
        }
      ]
    },
    {
      "externalId": "my_business_entity_456",
      "type": "IrsEin",
      "tin": "987654321",
      "businessName": "Acme Corporation",
      "address": {
        "address1": "456 Corporate Blvd",
        "address2": "Floor 10",
        "city": "Metropolis",
        "region": "NY",
        "country": "US",
        "postalCode": "10001"
      },
      "taxAccounts": [
        {
          "externalId": "my_tax_account_125",
          "type": "Corporate",
          "taxAuthority": "US_IRS"
        }
      ]
    }
  ]
}

Note: The activate field behaves as in Create a Taxpayer, and only when the taxpayer is created.

HTTP Response:

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

{
  "taxpayer": {
    "id": "029bc3f4-d65e-73f7-8133-f5800e825510",
    "externalId": "my_taxpayer_123",
    "userId": "049bc3f4-d65e-73f7-8133-f5800e825512",
    "status": "Active",
    "outcome": "Existing"
  },
  "taxEntities": [
    {
      "id": "039bc3f4-d65e-73f7-8133-f5800e825511",
      "externalId": "my_individual_entity_001",
      "outcome": "Existing",
      "taxAccounts": [
        {
          "id": "059bc3f4-d65e-73f7-8133-f5800e825513",
          "externalId": "my_tax_account_123",
          "outcome": "Existing"
        },
        {
          "id": "059bc3f4-d65e-73f7-8133-f5800e825514",
          "externalId": "my_tax_account_124",
          "outcome": "Created"
        }
      ]
    },
    {
      "id": "049bc3f4-d65e-73f7-8133-f5800e825512",
      "externalId": "my_business_entity_456",
      "outcome": "Created",
      "taxAccounts": [
        {
          "id": "059bc3f4-d65e-73f7-8133-f5800e825515",
          "externalId": "my_tax_account_125",
          "outcome": "Created"
        }
      ]
    }
  ]
}

In this example, the taxpayer and the individual tax entity already existed, so the response returns the stored data: the individual tax entity keeps the externalId it was created with (my_individual_entity_001), not the one sent in the request.

​
Outcomes

OutcomeMeaning
CreatedThis call created the resource
ExistingThis call returned the saved resource, without changing it

The taxpayer block also carries status (Active or Deactivated).

​
Client Application Scope

Only client applications with the all or firm:{firmId} scope can call this endpoint. Any other scope receives 403 Forbidden.

​
Validation

Validation errors name the property in the response body:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "TaxEntities": [
      "'Tax Entities' must not be empty."
    ]
  }
}

​
Error Handling

HTTP StatusWhen it happens
400 Bad RequesttaxEntities is empty, a tax entity has no taxAccounts, the payload repeats a tin across tax entities or a taxAuthority + type pair within a tax entity, a Personal tax account is on a business tax entity (or a Corporate one on an individual tax entity), or a field breaks the rules of the single-resource calls (Use Cases 3, 4 and 5)
401 UnauthorizedThe Authorization header is missing or invalid
403 ForbiddenThe firm is unknown or not linked to the client application, the client application scope is not all or firm:{firmId}, or the ownerFirmUserId user is not allowed to own clients
404 Not FoundownerFirmUserId does not belong to the firm
409 ConflictThe payload conflicts with existing data: a tin was found with a different type, or the user.emailAddress is already registered to a user outside the firm

​
Create a Taxpayer

Create only the taxpayer and its user, without tax entities or tax accounts.

Sequence of Events:

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

HTTP Request:

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

{
  "ownerFirmUserId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "externalId": "my_taxpayer_123",
  "name": "John Doe",
  "activate": false,
  "user": {
    "emailAddress": "john.doe@acme.com",
    "name": "John",
    "lastName": "Doe",
    "phoneNumber": "+1234567890"
  }
}

Note: The ownerFirmUserId field is optional. If provided, it associates the taxpayer with a specific firm user, and only that firm user will have access to manage the taxpayer. It’s highly recommended to set this field to ensure proper access control.

The referenced firm user 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 owner does not need to be active or to have accepted its invite.

Note: The activate field is optional (defaults to false). When true, the taxpayer’s user is created already active (isActive: true, inviteStatus: Accepted), skipping the invite/signup step. Use this when your users access Remitian exclusively through your application, e.g. with Passwordless Authentication (see Use Case 10).

HTTP Response:

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

{
  "id": "029bc3f4-d65e-73f7-8133-f5800e825510",
  "externalId": "my_taxpayer_123",
  "userId": "049bc3f4-d65e-73f7-8133-f5800e825512"
}

Note: userId is the created user’s id, the same value returned as items[].taxpayerUser.user.id in the List Taxpayers response. You do not need a follow-up GET /v1/firms/{firmId}/taxpayers?externalId=... call to obtain it.