Skip to content
English
More support
Contact us
  • There are no suggestions because the search field is empty.

Taxpayers

Create, list, deactivate and reassign taxpayers, and provision a taxpayer with its tax entities and tax accounts in one call.

What it is

A taxpayer is the container for a firm's client in Remitian. It holds the client's tax entities and tax accounts, and it is what you schedule tax payments and import tax forms against. Every taxpayer belongs to a firm and has its own user.

When you need it

  • A firm adds a new client in your system.
  • A client leaves the firm, or moves to a different accountant.
  • You want to set up a client, its tax entities and its tax accounts in a single request.

How it works

  1. Create the taxpayer with POST /v1/firms/{firmId}/taxpayers, sending your own ID in externalId, a name and the taxpayer user's details. The response includes the taxpayer id and the userId, so no follow-up lookup is needed.
  2. List taxpayers with GET /v1/firms/{firmId}/taxpayers, filtering by externalId or emailAddress (exact match, not case-sensitive).
  3. Reassign a taxpayer with POST /v1/firms/{firmId}/taxpayers/{taxpayerId}/change-owner-firm-user.
  4. Deactivate a taxpayer with DELETE /v1/taxpayers/{taxpayerId}.
  5. To create everything at once, use POST /v1/firms/{firmId}/taxpayers/provision. Remitian finds each resource by its key (taxpayer by email, tax entity by TIN, tax account by tax authority and type) and creates only what is missing.

Common questions

Should I set ownerFirmUserId?

It is optional but highly recommended. It ties the taxpayer to one firm user so only that user manages it. The owner must be an Admin or a user created with the CanOwnClients permission, otherwise the request returns 403 Forbidden. The owner does not need to have accepted their invite.

When should I use activate?

Set activate to true when your users reach Remitian only through your application, for example with passwordless access. The taxpayer user is created already active and skips the invite and sign-up step. It defaults to false.

Is the provision call safe to retry?

Yes, once the previous call has finished. It finds or creates, and never updates. If a resource already exists, the data you send for it is ignored, the response returns the stored data with an outcome of Existing, and the stored externalId may differ from the one you sent. A deactivated taxpayer is not reactivated.

Why did provisioning return 403 or 409?

Provisioning needs a client application scope of all or firm:{firmId}. A 409 Conflict means the payload clashes with existing data, for example a TIN already stored with a different type, or an email registered to a user outside the firm.

Full documentation