Integration using JSON
Introduction
JSON is a lightweight, text-based data format used for exchanging information between systems. It is both human-readable and machine-friendly, making it a widely accepted standard for data communication.
In TallyPrime, JSON integration enables seamless interaction between Tally and external applications through structured request and response messages. This allows businesses to:
- Exchange data such as masters,transactions and reports.
- Automate workflows by connecting Tally with web services, third-party applications, and enterprise systems.
- Improve efficiency by reducing manual intervention in data import/export processes.
With JSON support, TallyPrime becomes more flexible and adaptable to modern business needs, ensuring fast, reliable, and standardized data exchange across platforms.
Various Features of JSON Integration in TallyPrime
From TallyPrime 7.0 onwards, TallyPrime has been enabled with native JSON structure, where data exchange in JSON format is available as a default feature in the product itself like XML.
JSON Formats Supported
TallyPrime supports integration with third party applications in both Native JSON format and non-native JSON format.
- Native JSON Format: Tally understandable JSON format where the JSON data is structured as per the object schema of TallyPrime data. When data is available in this format, TallyPrime can directly consume this, with the default JSON import feature or a data push request over HTTP from third party application. In this case, no additional TDL coding is required for data import.
- Non-Native/ Custom JSON Format: When the third parties have their own JSON format, integration is still possible with the help of various TDL capabilities that can read JSON file locally and over HTTP and consume the data for further processing. Data can be sent to the third parties in JSON format supported by 2 versions of structures-version JSON(supported from Tally.ERP 9 6.2) and version JSONEX (supported from TallyPrime 7.0)
TallyPrime as Server and Client
- TallyPrime as Server: Here, data exchange is initiated by the third-party applications with TallyPrime, where data is pushed to TallyPrime or pulled from the product in JSON format.
- TallyPrime as Client: Here, data exchange is initiated by TallyPrime with third-party applications, where TallyPrime sends a GET or POST request to third-party applications.
Online and Offline Integration Support
- Online Integration: Data exchange can happen effortlessly over HTTP from third-party to TallyPrime with the prescribed HTTP Request-Response messaging format. In the same way JSON data from Third party can be read and consumed in TallyPrime using TDL capabilities with HTTP GET and POST methods.
- Offline Integration: JSON data in a file or JSON data from DLL can be read and consumed in TallyPrime using the TDL capabilities.
JavaScript Object Notation (JSON)
JSON format supports storing the data types: string, number, object, array, boolean, and null. The object and array are data structures. Other data types store leaf values. To know more about JSON refer JSON.
Comparison of JSON and XML Representations
The following example denotes a collection of 3 employee objects in the JSON and XML formats.
|
JSON |
XML |
|
{ “employeecount”: “3”, “employeedept”: “RnD”, “employees”: [ { “firstName”: “John”, “lastName”: “Doe” }, { “firstName”: “Anna”, “lastName”: “Smith” }, { “firstName”: “Peter”, “lastName”: “Jones” } ] } |
<Envelope> <employeecount>3</employeecount> <employeedept>RnD</employeedept> <employees> <employee> <firstName>John</firstName> <lastName>Doe</lastName> </employee> <employee> <firstName>Anna</firstName> <lastName>Smith</lastName> </employee> <employee> <firstName>Peter</firstName> <lastName>Jones</lastName> </employee> </employees> </Envelope> |
In the above example you can observe that:
- JSON format does not have end tags.
- It is short.
- Cannot duplicate the tags at the same level of the hierarchy.
Comparison of JSON and TallyPrime Data Types
|
JSON Data Type |
Corresponding Tally Data Type |
|
String |
Long, Amount, Rate, String, NamePtr, Time, FlagSet, RateX, Date, DateTime, NumSet, Quantity, DateRange, Duration |
|
Boolean |
Logical |
|
Object |
Tally Object |
|
Array |
Collection |
|
Number |
Number |
JSON Integration using HTTP – Request & Response Format
The HTTP Request structure in JSON format enables Third parties to fetch modify and create data objects in TallyPrime.
The request structure is divided into HTTP Headers and the Data Payload.
Since Data is stored in TallyPrime as objects, data can be fetched via Objects, Collection (Fetch group of objects), Reports (To get data structured in required JSON format), and Functions (To fetch specific information of data).
To post data to TallyPrime, i.e. to modify or create data, the data is structured in Tally native format in the data payload so that it can be directly consumed.
JSON Request Template:Headers
Purpose: It is the portion of a message that carries metadata about the request or response, rather than the actual business data itself. Its purpose is to provide information that helps the systems understand how to handle the payload. It often includes details like content type (JSON/XML), encoding, authentication tokens, request IDs, timestamps, or routing information.
List of headers available for JSON
|
Header |
Description |
Mandatory |
|
content-type |
Specifies the type of content sent from the third-party application to TallyPrime For Multilingual application/json;charset=utf-8 -> Specify this when the request is sent in ASCII or utf-8 BOM encoding. OR application/json;charset=utf-16 -> Specify this when the request is sent in utf-16 LE BOM encoding. In either of the cases TallyPrime responds in utf-16 only when charset is mentioned. NOTE: Ensure that the encoding mentioned in the charset matches the actual encoding in which the payload is sent as specified above in order to get required response For Others application/json ->charset is not required in this case |
Yes |
|
Version |
Takes the version number i.e. 1 |
Yes |
|
Tallyrequest |
Accepts values Export or Import Export: This value is used when data needs to be fetched from TallyPrime Import: This value is used when data needs to be posted to TallyPrime |
Yes |
|
Type |
Type of entity that needs to be requested can be Data, Collection, Object or Function. Data: Set this value, when Report data needs to be fetched or when Data is posted to TallyPrime(i.e. tallyrequest is set to import) Collection: Set this value, when Collection data needs to be fetched Object: Set this value, when data of a specific object needs to be fetched Function: Set this value when data from any platform function needs to be fetched, |
Yes |
|
Subtype |
Valid only for Object requests to specify the type of master Ex. Ledger, StockItem etc |
Yes, Only incase type is set as Object, Else NO. |
|
Id |
This header is the actual qualifier that specifies the name of the definition whose data must be fetched. Like the name of Report, Collection, Object or Function based on what’s specified in the header ‘type’. |
Yes |
|
id-encoded |
base 64 Encoded id |
Yes, Only in case of multilingual data fetch, else No |
|
detailed-response |
When data/objects are created /imported via http request from TPA, TallyPrime sends a response back to TPA with details of how many objects were created, altered, deleted and so on. Along with this, additional object counts can be sent in the response to the TPA in ‘cmp_info’ tag, based on the value specified in this header. This header takes Yes or No as values. |
No |
content-type : application/json
version : <Number>
tallyrequest : Import/Export/Execute
type : Object/Collection/Data/Function
id : <Value>
detailed-response: <Yes/No>
Example Mandatory Headers
content-type:application/json
version :1
tallyrequest:Import
type :Data
id :AllMasters
JSON Request Template:Body
Purpose: The body carries the actual business data that needs to be transmitted between systems. It contains the substantive content. Without the body, there is no meaningful data exchange; it is the part that holds the core information the sender wants the receiver to process.
|
Body Tags |
Purpose |
|
static_variables |
Specifies the values of the system variables that is necessary for the data exchange, so that the right data in the right format is fetched. Even the variables that are used in the configurations that affects export or import of data can be specified here. In further reading, the mandatory variables to be specified is mentioned. |
|
repeat_variables |
This is used in case of fetching data of a report where repeated variables are used. Variables that need to be repeated is specified here. |
|
fetchlist |
This is used to fetch storages/methods from an object. This is applicable only when the header ‘Type’ is Object |
|
func_param_list |
Applicable when the header ‘Type’ is ‘Function’. Specifies the parameters required for function execution. |
|
tdlmessage |
It is used to specify the TDL related information. The complete TDL to be executed to handle the Request; will be sent within the TDL block. This is specified when the TDL required for execution of the request is already not loaded/present in TallyPrime. TallyPrime will Load this TDL information first and then execute the request and respond accordingly. |
|
tallymessage |
This is applicable when ‘tallyrequest’ header is ‘import’, i.e. in the case of TPA sending request to create or modify actual data in TallyPrime. The actual data being transferred for import into TallyPrime is specified here. |
{
“static_variables”: [
{
“type”: “”,
“key”: “”,
“name”: “”,
“value”: “”
},
{}
],
“repeat_variables”: [
{
“type”: “”,
“key”: “”,
“name”: “”,
“value”: [
“”,
“”
]
},
{}
],
“fetchlist”: [
“fieldA”,
“fieldB”
],
“func_param_list”: [
{
“type”: “”,
“value”: “”
}
],
“tdlmessage”: [
{
“descriptions”: [
{
“metadata”: {},
“attributes”: []
},
{
“metadata”: {},
“attributes”: []
}
]
},
{
“definitions”: []
}
],
“tallymessage”: {}
}
Mandatory Variables Specification in static_variables
JSON Response Template
The Response contains the following sections which clearly informs whether a request has been successful or not and the relevant data that was requested.
{
“status”: “1/0”,
“cmp_info”: {
“_note”: “not appicable for data”
},
“parms”: [
“applicable for repeat variables”,
“each object contains the repeated vairables and value as key and value respectively”
],
“tallymessage”: [
“applicable for objects”,
“data flow where it is a full object export Ex. DayBook”
],
“data”: {
“_note”: “applicable for collection and data export”
},
“result”: {
“_note”: “applicable for function”
}
}
Export of Ledger
Request Header
content-type:application/json
version: 1
tallyrequest: export
type:collection
id:Ledger
Import of Ledger
Request Header
content-type:application/json
version:1
tallyrequest:Import
type:Data
id:All Masters
Export of Stock Item
Request Header
content-type:application/json
version: 1
tallyrequest: export
type:collection
id:StockItem
Import of Stock Item
Request Header
content-type:application/json
version: 1
tallyrequest: Import
type: Data
id: All Masters
Export of Voucher
Request Header
content-type:application/json
version: 1
tallyrequest: export
type:collection
id: TSPLVoucherColl
Import of Voucher
Request
content-type:application/json
version: 1
tallyrequest: Import
type: Data
id: Vouchers
Report Export – Without Empty Fields(Default)
Let’s take an example of a report “Balance Sheet” in Tally and understand how the request and response would look like in case of export.
Request Header
content-type:application/json
version: 1
tallyrequest: Export
type: Data
id: Balance Sheet
Report Export – With Empty Fields
A TDL code is sent in the tdlmessage tag of the request payload where the new Report level attribute “Export Empty Fields” to be set yes, so that even the empty fields of the report is sent in the response.
Request Header
content-type:application/json
version: 1
tallyrequest: Export
type: Data
id: Balance Sheet
JSON Integration Using TDL
TDL also supports integration with external systems that use JSON for data exchange. Developers can use TDL to both fetch and export structured JSON data using HTTP or local file sources. Here are the list of capabilities listed based on its application and usage.
HTTP Integration Capabilities
- External API to TallyPrime: External API initiates HTTP POST where JSON data is in the native Tally structure that can be directly posted to TallyPrime. And HTTP Get to fetch data in native format or custom/non-native format using report attributes.
- General Attributes
- Report Attributes
- Functions
- Import File & Attributes
- Import File Events
- TallyPrime to External API Using Custom JSON Format: TallyPrime uses TDL to fetch JSON from external APIs via HTTP GET and POST, where the report capabilities are used to construct the json requests along with headers.
- Collection Attributes
- General Attributes
- Report Attributes
- Actions
- Functions
File Based Integration Capabilities
-
Reading JSON File: Read JSON files stored locally into TallyPrime by mapping JSON objects to TDL collections. Following attributes are used to do the same.
-
Collection Attributes
-
Functions
-
-
File Based Report Export: Default and Customized Reports are exported using export feature of TallyPrime or Export action. Following attributes are used to create the required JSON structure to be exported.
-
General Attributes
-
Report Attributes
-
Action
-
Export
-
-
-
JSON Data export using Productivity Suites: Data can be exported to a JSON schema present in a file by providing mapping information in the Form. Following attributes are used for the same.
-
Form Attributes
-
Resource Attribute
-
Functions
-
-
File Based Import in Native JSON Format: JSON file where the data is in native structure which can be directly imported using import feature of TallyPrime or with the Import action. Following are the attributes that can be used to log information or modify objects during import.
-
Import File & Attributes
-
Import File Events
-
Functions
-
Action
-
Import
-
-
DLL Integration
-
Integration in JSON Format: TallyPrime interacts with the external DLLs where the data exchange happens in JSON Format. Following are the attributes available for the same.
-
Collection Attributes
-
Functions
-
General Attributes
-
Report Attributes
-
These capabilities allow Tally to integrate with a wide range of modern applications and services that rely on JSON for communication.
Version JSON vs Version JSONEX
The support for JSON format started from Tally.ERP 9 6.2 onwards. With the GST portal supporting JSON data exchange, from TallyERP 9 6.2 release, our customers could directly generate GSTR-1 and GSTR-2 in JSON format and upload it to the GST portal. This opened the JSON integration domain with the third parties as well.
Though JSON was not natively supported like XML in the product, with 6.2, you could address integrations with third-party applications which deliver and consume files in JSON format. For this, TDL – Integration capabilities were enriched to support JSON file based Import and Export (with UTF-8 encoding), over HTTP and locally.
The version of the JSON format with which the Reports were exported was internally called JSON( where to export a report in JSON format variable SVExportFormat was set to JSON, with Collection datasource HTTPJSON, the request was sent in this version)
The JSON attribute in TDL was originally introduced to enable developers to export or import data in JSON format using a Function or Collection as the data source, and while this worked well for simple, flat data exchanges, it soon revealed some key limitations:
-
Developers had to always map the data structure with Tally’s own structure through explicit TDL coding
-
Limited flexibility to transform or restructure data during export
-
Imports became restrictive when dealing irregular JSON formats.
Most integrations require standard JSON with clearly defined keys and valid structure, which the earlier approach could not easily support.
To address this and to provide a more consistent and integration-friendly experience, TallyPrime has introduced its own native JSON format along with an enhanced TDL capability in the form of the new attribute JSONEx (i.e. setting SVExportFormat to JSONEX for exporting report in JSONEX version, using collection datasource HTTPJSONEX / PluginJSON to send requests in the new format), that provides:
-
Well-structured JSON output with valid keys and syntax.
-
Simplified data handling during imports and exports.
-
Clear, predictable JSON for integrations with external systems.
Comparison between JSON and JSONEX
|
|
JSON |
JSONEX |
|
JSON Output |
In default report, Tag names are repeated in scrollable lines without any proper array name. |
In default report, Tag names are repeated in scrollable lines with array name starting from form, part, line and field. |
|
Ensuring Validity of JSON
|
In report, tag names getting repeated JSON is becoming invalid.
|
This give valid JSON as Curly {} and square [] brackets are properly matched.
|
|
Backward Compatibility |
JSON attribute is used in TDL capabilities for JSON format. |
New attribute introduced JSON Ex to support the TDL capabilities for exporting the native structured format. |
{
“ENVELOPE”: {
“BSName”: {
“DSPAccName”: {
“DSP DispName”: “Capital Account”
}
},
“BSAmt”: {
},
“BSName”: {
“DSPAccName”: {
“DSP DispName”: “Loans (Liability)”
}
},
“BSAmt”: {
},
“BSName”: {
“DSPAccName”: {
“DSP DispName”: “Current Liabilities”
}
},
“BSAmt”: {
},
“BSName”: {
“DSPAccName”: {
“DSP DispName”: “Profit & Loss A/c”
}
},
“BSAmt”: {
},
“BSName”: {
“DSPAccName”: {
“DSP DispName”: “Current Assets”
}
},
“BSAmt”: {
}
}
}
{
“bsbody”: {
“bsinfo”: {
“bssources”: {
“bsdetail”: [
{
“bsname”: {
“dspaccname”: {
“dspdispname”: “Capital Account”
}
},
“bsamt”: [
{
}
]
},
{
“bsname”: {
“dspaccname”: {
“dspdispname”: “Loans (Liability)”
}
},
“bsamt”: [
{
}
]
},
{
“bsname”: {
“dspaccname”: {
“dspdispname”: “Current Liabilities”
}
},
“bsamt”: [
{
}
]
},
{
“bsname”: {
“dspaccname”: {
“dspdispname”: “Profit & Loss A/c”
}
},
“bsamt”: [
{
}
]
}
]
},
“bsapp”: {
“bsdetail”: [
{
“bsname”: {
“dspaccname”: {
“dspdispname”: “Current Assets”
}
},
“bsamt”: [
{
}
]
}
]
}
}
}
}
Use JSONEx for all new integrations, as it ensures well-structured, valid, and predictable JSON output. The original JSON attribute remains available for backward compatibility, but JSONEx is the recommended approach for clean and reliable integration with TallyPrime.
