Overview

Partner API is designed for platforms that file for multiple customer's through a single TaxBandits API account. Each customer is set up as a Managed User, which keeps its businesses, recipients, and returns separate from those of every other customer.

You continue to use one set of credentials, one account balance, and one webhook. Your customer's do not log in to TaxBandits. All activity runs through your integration.

Why use Partner API

Without Partner API, all of your customer's businesses are stored together under one account. If two customer's add a business with the same TIN, they share a single record, and the most recent update replaces the earlier details, including the business name and address.

With Partner API, each customer has its own separate space. The same TIN can exist under two customer's without either one affecting the other.

Scenario	Single API account	Partner API
Customer A saves a business with a given TIN	Saved	Saved under Customer A
Customer B saves a business with the same TIN and a different address	Replaces Customer A’s details	Saved under Customer B
Outcome	Customer A's business information is overwritten	Each customer’s information remains intact

How it works

1. Register each customer once. You provide your own reference for the customer, and TaxBandits returns a token that identifies that customer.
2. Request an access token for the customer. Include the customer’s reference and token in the access token request. Providing the customer’s reference is optional but recommended to ensure consistent customer identification and avoid potential conflicts in future API requests. The access token will be linked to the specified customer.
3. File as usual. Use the access token with the same Business, Recipient, and Form endpoints you use today. Each request applies to that customer’s data only.

To enable Partner API access for your account, please contact us at developer@taxbandits.com. See Getting Started for the steps.

What changes in your integration

• No new filing endpoints. The Business, Recipient and Form endpoints remain the same.
• One new endpoint. registerpartner registers a customer and returns its token.
• One addition to the access token request. A new field, partnerUser, identifies the customer.
• No new credentials. Your existing Client ID, Client Secret and User Token continue to apply.
• Gradual adoption. Requests that do not include partnerUser work exactly as they do today, so you can move customer's over in stages.

Key terms

Term	Description
Partner	Your API account, once Partner API is enabled.
Managed User	A customer registered under your account. Its data is stored separately.
Ref	Your unique reference for a customer, such as CUST-1001. Each Ref must be unique within your account.
Partner user token	A secret returned when you register a customer. It is required to act on that customer’s behalf.
UserType	The type of customer: BO (Business Owner).
Partner Flow	Any request that includes partnerUser.

What remains with your account

Customer records are kept separate, while billing and configuration stay with your main account.

Area	Managed at	What this means
Businesses, recipients, returns and TIN checks	Customer	Each customer’s records are kept separate.
Credits, balance and pricing	Your account	Transmission charges are deducted from your balance. Customer's do not hold separate balances.
API settings, including portal and email customization	Your account	One configuration applies to all of your customer's.
PDF generation	Your account	Return PDFs are generated using your API settings.
Status notifications (webhooks)	Your account	Updates for all customer's are sent to your webhook URL. Each update includes return or business identifiers, so you can match it to the right customer.

Important to know

• Store the token securely. The token is returned only once, at registration. If it is lost, contact TaxBandits support to reset it.
• One access token per customer. To work on a different customer, request a separate access token using that customer’s reference and token.
• Webhooks are managed by you. Customer's cannot configure their own webhooks.

Currently, the endpoints to view, list, update, deactivate, and reactivate customer's, and to reset a token aren’t available. Until they are available, contact TaxBandits support to deactivate, reactivate, or reset a customer’s token.

Getting Started

Partner API is available on request. Once TaxBandits enables it for your account, you register each customer once. After that, you request an access token for a customer whenever you file on its behalf.

Before you begin

Have the following ready:

• Your existing Client ID, Client Secret, and User Token
• A unique reference (Ref) for each customer, such as CUST-1001
• A secure place to store each customer's token

Setup at a glance

Step	What you do
1	Request Partner API for your account
2	Register each customer
3	Request an access token for the customer
4	Call the API as usual
5	Test in Sandbox, then go live

Step 1: Request Partner API

Contact TaxBandits support or your account manager and ask for Partner API to be enabled on your API account. TaxBandits will enable it and set up your account as a Partner.

Keep using your existing Client ID, Client Secret, and User Token. No new credentials are issued.

Requests that do not include partnerUser continue to work exactly as before, so you can move customer's over gradually.

Step 2: Register each customer

Call Register once for each customer, using your own Ref for that customer. Save the token that is returned, because it is shown only once. See Register.

Step 3: Request an access token for the customer

Add the partnerUser field, containing the customer’s ref and token, to your access token request. See Authentication.

Step 4: Call the API as usual

Use the access token with the existing 2.0.0 Business, Recipient and Form endpoints. Every call applies to that customer’s data. Access tokens are valid for one hour, so request a new one when the current one expires.

Filing calls run against the customer's data. Billing, PDFs and status webhooks are handled by your Partner account.

Step 5: Test in Sandbox, then go live

Complete the flow in Sandbox, then follow the standard Request to Go Live process.

Register

Use this endpoint to register one of your customer's as a Managed User under your Partner account. The response returns the token you need to act on that customer’s behalf.

To register the partner, you must first call the Auth method to obtain an access token. Include this token in your request header as a Bearer token. Refer to OAuth 2.0 Authentication for details on JWT-based authentication.

Key points

• Use your standard access token. Call Register with an access token requested without partnerUser.
• Save the token. It is returned only once, and TaxBandits stores it in a secure, hashed form. If it is lost, contact TaxBandits support to reset it.
• API access only. Managed Users cannot log in to the portal.

Endpoint: POST /v2/registerpartner

Request Body

Field	Type	Description
PartnerUser	Object	Details of the customer to register
Ref	String	Your unique reference for the customer. Must be unique within your Partner account. Required
ContactName	String	Optional customer’s contact name.
PhoneNumber	String	Optional customer’s phone number.
UserType	String	Optional kind of customer. Allowed values: BO

Request JSON

Sample 1 — Register a Business Owner

Request

{
"PartnerUser": {
  "Ref": "CUST-1001",
  "ContactName": "John Smith",
  "PhoneNumber": "9876543210",
  "UserType": "BO"
}
}

Response Body

Field	Type	Description
StatusCode	Number	HTTP status code
StatusName	String	Name of the status code
StatusMessage	String	Detailed status message
PartnerUser	Object	Registered customer
Ref	String	Ref as sent
Token	String	Partner user token. Use it in the partnerUser JWS claim. Returned only in this response.
UserType	String	BO as sent
Errors	Object[]	Validation errors, if any

Response JSON

200 - OK

{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API Call",
"PartnerUser": {
  "Ref": "CUST-1001",
  "Token": "f96e4efe67894b5dbc020e3e78462a88",
  "UserType": "BO"
},
"Errors": null
}

409 - Conflict

{
"StatusCode": 409,
"StatusName": "Conflict",
"StatusMessage": "Ref already registered",
"Errors": [
  {
    "Id": "PARTNERUSER-002",
    "Name": "Ref",
    "Message": "CUST-1001 is already registered for this Partner"
  }
]
}

403 - Forbidden

{
"StatusCode": 403,
"StatusName": "Forbidden",
"StatusMessage": "Permission Denied.",
"PartnerUser": null,
"Errors": [
  {
    "Id": "AUTH-100062",
    "Name": "PartnerFlow",
    "Message": "Partner flow is not enabled for this account. Please contact TaxBandits support to enable it."
  }
]
}

400 - Bad Request

{
"StatusCode": 400,
"StatusName": "BadRequest",
"StatusMessage": "A validation error has occurred.",
"PartnerUser": null,
"Errors": [
  {
    "Id": "AUTH-100080",
    "Name": "PartnerUser.ContactName",
    "Message": "Invalid contactName. ContactName must have alphabetic character."
  }
]
}

Authentication

Partner API uses the same two-step process as OAuth 2.0 Authentication. You create a signed request, called a JWS, and exchange it for an access token. The only difference is one additional field, partnerUser, which identifies the customer.

Step 1 — Generate the JWS

Header

JWS Header

{
"alg": "HS256",
"typ": "JWT"
}

Payload

JWS Payload

{
"iss": "968a9c78dae29a29",
"sub": "968a9c78dae29a29",
"aud": "a574b75f18b24fc09f9039ffb5cb08f3",
"iat": 1790323200,
"scope": "fullaccess",
"categories": ["all"],
"partnerUser": {
  "ref": "CUST-1001",
  "token": "3f6c2a4e91b74d0ebb4a6a7e2d9c1f05"
}
}

JWS claims

Claim	Description	Required
iss	Issuer — Client ID from the console	Yes
sub	Subject — Client ID from the console	Yes
aud	Audience — User Token from the console	Yes
iat	Issued at, Unix epoch seconds	Yes
scope	Read / Write / Read_Write / Transmit / FullAccess	Optional
categories	Form groups the token can access	Required if scope is not FullAccess
partnerUser	Object identifying the customer. Its presence marks a Partner Flow request	Yes, for Partner Flow
partnerUser.ref	The Ref used at registration	Yes, for Partner Flow
partnerUser.token	The Token returned by Register	Yes, for Partner Flow

Signature: Sign the header and payload with your Client Secret using HS256. The JWS is valid for 5 minutes from iat.

Claim keys inside the JWS use camelCase (partnerUser, ref, token). API responses keep the 2.0.0 PascalCase style (PartnerUser, Ref).

Step 2 — Submit the Token Request

Endpoint: GET v2/token

• Sandbox: https://testoauth.expressauth.net/v2/token
• Live: https://oauth.expressauth.net/v2/token

Header

Header	Value	Required
Authentication	The JWS from Step 1	Yes

Success response

200 - OK

{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API Call",
"AccessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6InRiLTIwMjYtMDkiLCJ0eXAiOiJKV1QifQ...",
"TokenType": "Bearer",
"ExpiresIn": 3600,
"PartnerUser": {
  "Ref": "CUST-1001",
  "UserType": "BO"
},
"Errors": null
}

Field	Description
AccessToken	JWT to send as the Bearer token on all 2.0.0 calls for this customer
ExpiresIn	Token lifetime in seconds (3600 = 1 hour)
PartnerUser.Ref	Ref sent in the JWS
PartnerUser.UserType	BO, as registered. Empty if not set

PartnerUser is returned only for Partner Flow requests. The default response is unchanged.

Step 3 — Use the Access Token

Send the access token as Authorization: Bearer <AccessToken> on the Business, Recipient, and Form endpoints. All data you create or read belongs to the customer named in partnerUser.ref.

To work on another customer, request a separate access token using that customer’s ref and token.

Billing, PDFs & Webhooks

With a Partner Flow access token, filing data belongs to the customer, while charges, PDFs and webhooks are handled by your main Partner account.

Operation	Handled by
Create, update, get, list and delete Businesses, Recipients and Forms	Customer (Managed User)
TIN uniqueness and duplicate checks	Customer
Status, PDF and utility lookups on returns	Customer
Credit or cash balance check and deduction on Transmit	Partner
API configuration, including portal and email customization	Partner
PDF generation for transmitted returns	Partner's API settings
Status webhooks (Accepted, Rejected and so on)	Partner's webhook URL

Billing

Transmission charges are deducted from your Partner account’s credits or cash balance. Customer's do not have separate balances.

PDFs

PDFs for your customer's returns are generated with your Partner account's API settings, the same as for returns filed under your main account.

Webhooks

Status webhooks for every customer's returns are sent to the webhook URL configured on your Partner account. The payload is the standard 2.0.0 webhook payload; no Partner-specific fields are added. Use the return or business identifiers in the payload to match the update to your customer.

Customer's cannot configure their own webhooks.

Error Codes

Partner API returns the existing AUTH errors plus the partner-specific errors below. Error IDs marked new are proposed.

Authentication errors

Error ID	Name	Message
AUTH-100009	Referer	Invalid Referer value in the request
AUTH-100010	Referer	Referer value is required
AUTH-100017	Authorization	JWT Invalid
AUTH-100018	Authorization	JWT EXPIRED
AUTH-100019	Authorization	Invalid IP Address
AUTH-100026	Authorization	Authorization Failed
AUTH-100027	Authorization	Invalid Authorization Token
AUTH-100081	Authorization	Authorization is required

Register errors

Error ID	Name	Message
AUTH-100062	PartnerFlow	Partner flow is not enabled for this account. Please contact TaxBandits support to enable it.
AUTH-100063	PartnerUser	Either PartnerUser Ref or Token is required in the partnerUser claim.
AUTH-100064	PartnerUser.Ref	Invalid PartnerUser Ref. The Ref must not exceed 50 characters and must not contain +.
AUTH-100065	PartnerUser.Token	Invalid PartnerUser Token.
AUTH-100066	PartnerUser.Ref	The PartnerUserRef is not associated with the given PartnerUser token.
AUTH-100067	PartnerUser.Token	The PartnerUser Token does not match the registered token for the given Ref.
AUTH-100068	PartnerUser	Unable to process the partner user request at this time. Please try again later.
AUTH-100069	PartnerUser.Ref	PartnerUser Ref is required.
AUTH-100070	PartnerUser.Ref	The PartnerUser Ref is already registered for this partner.
AUTH-100071	PartnerUser.UserType	Invalid UserType. Allowed values are BO.
AUTH-100073	Authorization	A partner user access token cannot be used to register a partner user. Use the API user's access token.
AUTH-100075	PartnerUser.PhoneNumber	Invalid phone number. Only numeric digits are allowed, and the phone number must contain 10 to 15 digits.
AUTH-100076	PartnerUser.Ref	The PartnerUser Ref is not registered.
AUTH-100077	PartnerUser.token	The PartnerUser token is invalid.
AUTH-100078	PartnerUser.ContactName	ContactName should not exceed 70 characters.
AUTH-100079	PartnerUser.ContactName	Contact name must contain at least 3 characters.
AUTH-100080	PartnerUser.ContactName	Invalid contactName. ContactName must have alphabetic character.
AUTH-100081	Authorization	Authorization is required.
AUTH-100082	Ref	Ref must be at least 8 characters.
AUTH-100083	EmailAddress	Email Address cannot be more than 100 characters.
AUTH-100084	ContactName	Invalid contactName. The following special characters are not allowed: < > ; { } [ ] _ \ ! : ? =

Sample Error JSON

403 - Forbidden

{
"StatusCode": 403,
"StatusName": "Forbidden",
"StatusMessage": "Managed user is inactive",
"Errors": [
  {
    "Id": "AUTH-PARTNER-403",
    "Name": "PartnerUser",
    "Message": "The managed user CUST-1001 is not active"
  }
]
}