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. |
422 |
Unprocessable Content. The server understands the request payload and its syntax is correct, but it cannot process the instructions because of semantic errors or validation rules. |
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]" }
]
}
For any non-2xx outcome, the API returns a standardized error envelope. The HTTP-style status code used follows the guidance in §2.2 Common Status Codes (e.g., 400, 401, 403, 404, 409, 422, 429, 5xx).
Validation failures specifically use 422 Unprocessable Content.
| Field | Type | Description |
|---|---|---|
statusCode |
integer | HTTP-style status code for the response (see §2.2). |
statusDescription |
string | Human-readable status text summarizing the failure. |
responseId |
string | Unique identifier for tracing this specific response. Useful when contacting support. |
error |
object | Structured error metadata describing the exact validation failure. |
error objectThe error object provides structured details about the validation failure:
| Field | Type | Description |
|---|---|---|
code |
string | Machine-readable error code that uniquely identifies the specific validation error. |
details |
string | Human-readable explanation of the error, typically referencing the missing or invalid field. |
hint |
string | Optional guidance to resolve the error (e.g., formatting tips). |
Note: Clients should use the
codefield for programmatic handling and not depend on the wording ofdetails, which is intended for display or logging.
{
"statusCode": 422,
"statusDescription": "Validation error.",
"responseId": "c9f4e8b7-1234-5678-9abc-abcdef123456",
"error": {
"code": "SSN_REQUIRED",
"details": "The SSN field is required."
}
}
{
"statusCode": 422,
"statusDescription": "Unprocessable Content.",
"responseId": "b1a4d2a7-2f33-4e60-9c8c-4d3b7db8a0f1",
"error": {
"code": "TRANSMITTER_NOT_IDENTIFIED",
"details": "Unable to determine the transmitter associated with this API client.",
"hint": "Provide transmitterCode and/or etin in the request to enable routing."
}
}
Below are common error.code values returned when required fields are missing:
| Code | Description | |
|---|---|---|
TAX_YEAR_REQUIRED |
taxYear is required. |
|
FILING_YEAR_REQUIRED |
filingYear is required. |
|
FIRST_NAME_REQUIRED |
firstName is required. |
|
LAST_NAME_REQUIRED |
lastName is required. |
|
DOB_REQUIRED |
dob is required. |
|
SSN_REQUIRED |
ssn is required. |
|
ADDRESS_LINE1_REQUIRED |
addressLine1 is required. |
|
CITY_REQUIRED |
city is required. |
|
STATE_REQUIRED |
state is required. |
|
POSTAL_CODE_REQUIRED |
postalCode is required. |
|
TRANSMITTER_NOT_IDENTIFIED |
Unable to determine the transmitter associated with the requesting API client. |
|
TRANSMITTER_RESOLUTION_FAILED |
When transmitter resolution fails due to identifier mismatch or the resolved transmitter is not mapped to the authenticated client. | reason: "IDENTIFIER_MISMATCH" or "NOT_MAPPED_TO_CLIENT"; details: message; optionally fields: [{ "field": "transmitterCode" }, { "field": "etin" }] |
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. |
currency |
string | No | Currency code (default: USD). |
filingType |
string | No | Specifies the type of filing. Accepted values are: • BankApp (Default) — a bank application return submission. • Amendment — a corrected or updated return submission. |
transmitterCode |
string | No | A unique identifier assigned by Refundo to a partner transmitter system. It is used to distinguish and route inbound API requests. |
etin |
string | No | Electronic Transmitter Identification Number (ETIN): A five-digit ID number assigned by the IRS to a participant in IRS e-file that performs activity of transmission and/or software development. |
efin |
string | No | Electronic Filing Identification Number (EFIN): A six-digit ID number assigned by the IRS for e- filing. |
ptin |
string | No | Preparer Tax Identification Number (PTIN): An eight-digit ID number that starts with a “P.” Anyone who prepares or assists with preparing federal tax returns. |
{
"referenceId":"acct-001",
"taxYear": 2020,
"filingYear": 2021",
"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",
"bankAccountType": "Bankapp",
"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. See Request Body Parameters section for field definitions.
[
{
"referenceId":"acct-001",
"taxYear": 2024,
"filingYear": 2025",
"firstName": "John",
"lastName": "Smith",
"dob": "1982-03-15",
"ssn": "111-22-3333",
"addressLine1": "123 Main St",
"city": "Miami",
"state": "FL",
"postalCode": "33101",
"bankAccountType": "Bankapp",
"currency": "USD",
"efin": "654321",
"ptin": "P65432100"
},
{
"referenceId":"acct-002",
"taxYear": 2024,
"filingYear": 2025",
"firstName": "Laura",
"lastName": "Green",
"dob": "1991-11-30",
"ssn": "444-55-6666",
"addressLine1": "456 Oak Ave",
"city": "Dallas",
"state": "TX",
"postalCode": "75001",
"bankAccountType": "Bankapp",
"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.Audience: Teams integrating with Refundo as an e-file transmitter or software partner.
Programmatic handling
error.code; do not parse or rely on details/hint text.422 as an actionable validation issue (fix input, then resend).429 (rate limit) or transient 5xx errors.responseId to correlate client logs with Refundo support.What to include on every request
transmitterCode (Refundo-issued) and etin (IRS 5-digit).etin: exactly 5 numeric digits (^[0-9]{5}$).transmitterCode: use the exact value assigned by Refundo (case-sensitive; do not trim, abbreviate, or transform).Mapping checklist
etin on file matches your IRS enrollment.Error-handling pattern (pseudocode)
if statusCode == 422:
switch error.code:
case "TRANSMITTER_NOT_IDENTIFIED":
// Add transmitterCode and/or etin; verify mapping; resend after correction
case "TRANSMITTER_IDENTIFIER_INVALID":
// Fix format/lookup issues (e.g., etin must be 5 digits) and resend
case "TRANSMITTER_IDENTIFIER_MISMATCH":
// Ensure transmitterCode and etin resolve to the same transmitter
case "TRANSMITTER_NOT_MAPPED_TO_CLIENT":
// Contact your admin/Refundo to link identifiers to your API credentials
else if statusCode == 429:
// Exponential backoff + retry with jitter
else if 500 <= statusCode < 600:
// Retry with jitter; escalate if persistent
log(responseId)
Minimal request example
{
"transmitterCode": "ACME-TX-001",
"etin": "12345",
"... other payload ..."
}
Tip: For multi-tenant platforms, inject transmitterCode/etin at the tenant/account boundary and have your SDK or middleware attach them automatically to all outbound API calls.
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.