This page defines the API specification for Refundo. It provides a structured reference for developers integrating with the Refundo platform. Topics covered include:
The API is designed to be secure, developer-friendly, and compliant with financial and government data handling standards. The API is modular, consistent in design, and optimized for integration with both cloud and on-premise systems.
https://api.refundo.com/api/trbs/v1
Authorization: Bearer {Base64(clientid:secret)}
| Header | Type | Required | Description |
|---|---|---|---|
Authorization |
string | Yes | Bearer token for authentication. |
Content-Type |
string | Yes | application/json for request payloads. |
To support development, sandbox testing, and simulation workflows, the Refundo API accepts an optional request header: X-TRBS-Mode.
| Header Name | Value | Description |
|---|---|---|
| X-TRBS-Mode | Test | Indicates the request is running in test mode. No real-world actions occur. |
| X-TRBS-Mode | Debug | Enables enhanced logging and trace output. |
Best Practice: Remove the
X-TRBS-Modeheader before promoting integrations to production environments.
When the header X-TRBS-Mode: Test is set:
[TEST MODE] prefix in the statusDescription.responseId is prefixed with test-.POST https://api.refundo.com/api/trbs/v1/transmitter/bankaccount HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
X-TRBS-Mode: Test
{
"statusCode": 200,
"statusDescription": "[TEST MODE] Bank Account record created successfully.",
"responseId": "test-c4f1e678-9012-4567-89ab-1234567890cd",
"data": {
...
}
}
All API responses contain the following fields:
| Field | Type | Description |
|---|---|---|
statusCode |
integer | HTTP-like status code representing success or failure. |
statusDescription |
string | A brief description of the response outcome. |
responseId |
string | A unique identifier for debugging and tracing. |
data |
object/array/null | The actual data payload (if applicable). |
Example:
{
"statusCode": 200,
"statusDescription": "Request completed successfully.",
"responseId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"data": {
"exampleField": "exampleValue"
}
}
The Refundo API returns standardized HTTP-style status codes to indicate the result of each request. Below is a reference of commonly used status codes across the platform:
| Status Code | Description |
|---|---|
200 |
OK. The request was successful. |
201 |
Created. A new resource was successfully created. |
204 |
No Content. The request was successful but no content is returned. |
400 |
Bad Request. The request was invalid or malformed. |
401 |
Unauthorized. The request lacks valid authentication credentials. |
403 |
Forbidden. The user does not have permission to perform the action. |
404 |
Not Found. The requested resource does not exist. |
409 |
Conflict. The request could not be completed due to a resource conflict. |
429 |
Too Many Requests. The rate limit has been exceeded. |
500 |
Internal Server Error. A generic error occurred on the server. |
503 |
Service Unavailable. The server is temporarily unable to handle the request. |
| Field | Type | Description |
|---|---|---|
page |
integer | Current page number. |
perPage |
integer | Number of items per page. |
totalItems |
integer | Total number of records available. |
data |
array | Array of items. |
Example:
{
"statusCode": 200,
"statusDescription": "Tax Payers retrieved successfully.",
"responseId": "f7d2c839-75b1-4f12-bc2f-91234abcde99",
"page": 1,
"perPage": 10,
"totalItems": 5,
"data": [
{ "taxpayerId": 12345, "firstName": "John", "email": "[email protected]" },
{ "taxpayerId": 12346, "firstName": "Jane", "email": "[email protected]" }
]
}
| Field | Type | Description |
|---|---|---|
statusCode |
integer | HTTP-style error code. |
statusDescription |
string | Description of the failure. |
responseId |
string | Unique ID for tracing the error. |
error |
object | Error metadata. |
Example:
{
"statusCode": 400,
"statusDescription": "Invalid request parameters.",
"responseId": "c9f4e8b7-1234-5678-9abc-abcdef123456",
"error": {
"code": 400,
"details": "The SSN field is required."
}
}
Example:
{
"statusCode": 429,
"statusDescription": "Too many requests. Please try again later.",
"responseId": "def12345-6789-0abc-def1-234567890abc"
}
responseId allows traceability for debugging and auditing.Creates or updates the taxpayer record and generates a new bank account if none exists. This endpoint is used by transmitters to streamline taxpayer onboarding and refund account setup in a single API call.
Endpoint:
POST https://api.refundo.com/api/trbs/v1/transmitter/bankaccount
| Field | Type | Required | Description |
|---|---|---|---|
referenceId |
string | No | Caller-defined identifier returned in response for matching. |
taxYear |
integer | Yes | The period for which your income and expenses are tracked and taxes are calculated. |
filingYear |
integer | Yes | The year when the tax return was submitted. |
firstName |
string | Yes | Taxpayer’s first name. |
lastName |
string | Yes | Taxpayer’s last name. |
middleInitial |
string | No | Middle initial. |
dob |
string | Yes | Date of birth (YYYY-MM-DD). |
email |
string | No | Taxpayer email. |
phone |
string | No | Phone number. |
ssn |
string | Yes | Social Security Number. |
addressLine1 |
string | Yes | Address line 1. |
addressLine2 |
string | No | Address line 2. |
city |
string | Yes | City of residence. |
state |
string | Yes | 2-letter state code. |
postalCode |
string | Yes | ZIP or postal code. |
| Field | Type | Required | Description |
|---|---|---|---|
currency |
string | No | Currency code (default: USD). |
bankAccountType |
string | Yes | Bankapp or Amendment. |
| Field | Type | Required | Description |
|---|---|---|---|
efin |
string | No | ERO’s Electronic Filing ID |
| Field | Type | Required | Description |
|---|---|---|---|
ptin |
string | No | Preparer Tax ID Number |
{
"referenceId":"acct-001",
"firstName": "Jane",
"lastName": "Doe",
"dob": "1990-05-10",
"ssn": "123-45-6789",
"addressLine1": "456 Elm St",
"city": "Springfield",
"state": "NY",
"postalCode": "10001",
"email": "[email protected]",
"currency": "USD",
"efin": "123456",
"ptin": "P12345678"
}
{
"statusCode": 201,
"statusDescription": "Bank Account created and taxpayer onboarded.",
"responseId": "tx-abc123-def456-ghi789",
"data": {
"referenceId":"acct-001"
"bankAccountId": 1015,
"taxPayerId": 3002,
"routingNumber": "021000021",
"accountNumber": "****9012",
"accountType": "Checking",
"taxPreparerId": 7891
}
}
Creates multiple bank accounts for taxpayers in one request. This bulk endpoint performs the same logic as the single taxpayer endpoint but accepts an array and returns an array of responses.
Endpoint:
POST https://api.refundo.com/api/trbs/v1/transmitter/bulk/bankaccount
An array of objects containing taxpayer, bank account, ERO, and preparer fields.
| Field | Type | Required | Description |
|---|---|---|---|
referenceId |
string | No | Caller-defined identifier returned in response for matching. |
taxYear |
integer | Yes | The period for which your income and expenses are tracked and taxes are calculated. |
filingYear |
integer | Yes | The year when the tax return was submitted. |
firstName |
string | Yes | Taxpayer’s first name. |
lastName |
string | Yes | Taxpayer’s last name. |
middleInitial |
string | No | Middle initial. |
dob |
string | Yes | Date of birth (YYYY-MM-DD). |
email |
string | No | Taxpayer email. |
phone |
string | No | Phone number. |
ssn |
string | Yes | Social Security Number. |
itin |
string | No | Individual Taxpayer Identification Number. |
tin |
string | No | Taxpayer Identification Number. |
ein |
string | No | Employer Identification Number. |
addressLine1 |
string | Yes | Address line 1. |
addressLine2 |
string | No | Address line 2. |
city |
string | Yes | City of residence. |
state |
string | Yes | 2-letter state code. |
postalCode |
string | Yes | ZIP or postal code. |
| Field | Type | Required | Description |
|---|---|---|---|
currency |
string | No | Currency code (default: USD). |
bankAccountType |
string | Yes | Bankapp or Amendment. |
| Field | Type | Required | Description |
|---|---|---|---|
efin |
string | No | ERO’s Electronic Filing ID |
| Field | Type | Required | Description |
|---|---|---|---|
ptin |
string | No | Preparer Tax ID Number |
[
{
"referenceId":"acct-001",
"firstName": "John",
"lastName": "Smith",
"dob": "1982-03-15",
"ssn": "111-22-3333",
"addressLine1": "123 Main St",
"city": "Miami",
"state": "FL",
"postalCode": "33101",
"currency": "USD",
"efin": "654321",
"ptin": "P65432100"
},
{
"referenceId":"acct-002",
"firstName": "Laura",
"lastName": "Green",
"dob": "1991-11-30",
"ssn": "444-55-6666",
"addressLine1": "456 Oak Ave",
"city": "Dallas",
"state": "TX",
"postalCode": "75001",
"currency": "USD",
"efin": "654321",
"ptin": "P65432100"
}
]
[
{
"statusCode": 201,
"statusDescription": "Bank Account successfully created.",
"responseId": "resp-a1",
"data": {
"referenceId":"acct-001",
"bankAccountId": 2001,
"taxPayerId": 4001,
"routingNumber": "021000021",
"accountNumber": "****5678",
"accountType": "Checking",
"taxPreparerId": 501
}
},
{
"statusCode": 201,
"statusDescription": "Bank Account successfully created.",
"responseId": "resp-a2",
"data": {
"referenceId":"acct-002"
"bankAccountId": 2002,
"taxPayerId": 4002,
"routingNumber": "021000021",
"accountNumber": "****9012",
"accountType": "Checking",
"taxPreparerId": 501
}
}
]
400 and an error field describing the issue.To begin using the Refundo API, you must request access credentials from the platform team.
To obtain credentials, please contact the API provisioning team:
Once approved, you will receive a secure package with credentials and integration guidelines.
Note: All API access is logged and monitored. Credentials must be stored securely.
For any technical questions, integration issues, or API-related bugs, please reach out to the Refundo support team.
Support hours: Monday to Friday, 9AM – 5PM EST
When contacting support, always include your
responseId, API URL, and timestamp of the request if possible.