- Use Case 3: Manage Taxpayers
- Provision and Create Taxpayers
Use Case 3: Manage Taxpayers
Provision and Create Taxpayers
Find or create a taxpayer with its tax entities and tax accounts in a single call, or create only the taxpayer.
There are two ways to create a taxpayer in a firm:
- Provision a Taxpayer with Tax Entities and Tax Accounts is the more complete action: one call finds or creates the taxpayer, its tax entities and their tax accounts.
- Create a Taxpayer creates only the taxpayer and its user. You then add tax entities and tax accounts with Use Case 4 and Use Case 5.
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
| Resource | Key | Scope |
|---|---|---|
| Taxpayer | user.emailAddress | The firm |
| Tax entity | tin | The taxpayer |
| Tax account | taxAuthority + type | The 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
externalIdcan differ from the one sent. externalIdis 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
Existingwithstatus: Deactivated.
Sequence of Events:
- Your system sends the taxpayer, its tax entities and their tax accounts in one request
- Remitian validates the whole payload, then finds or creates each resource by its key in a single transaction
- Remitian responds with
200 OKand anoutcomefor each resource - Your system can then use the returned ids for subsequent operations
Request Structure
| Field | Type | Description |
|---|---|---|
taxpayer | Object | The 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 |
taxEntities | array | The 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[].taxAccounts | array | The 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
| Outcome | Meaning |
|---|---|
Created | This call created the resource |
Existing | This 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 Status | When it happens |
|---|---|
400 Bad Request | taxEntities 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 Unauthorized | The Authorization header is missing or invalid |
403 Forbidden | The 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 Found | ownerFirmUserId does not belong to the firm |
409 Conflict | The 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:
- Your system sends a request to create a taxpayer using an external ID and associates it with an existing firm
- Remitian responds with the created taxpayer’s details
- Your system can then use this
taxpayerIdanduserIdfor 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.