Ingest: guide
Help release c4e6d48f22a45602 · Generated 22 November 2026. Online at docs.mycadesk.in/modules/ingest/.
Help explains how the software works and is not professional advice; refer to the statute or notification.
Data imports and connected books
How client data gets into the app (uploads, bulk zips, the Tally connector, Zoho Books, Busy exports), how it is checked and published as datasets, and how the firm's billing goes back out to Tally.
Everything the app knows about a client's returns and books comes in through Data imports
(/imports) or Connected books (/books). Each source is read, checked and, when it passes,
published as a dataset: a versioned, read-only copy that reconciliation, GST annual work, TDS
and other modules use. The app never writes into a client's books or a portal.
Ways data comes in
| Source | Where | Read more |
|---|---|---|
| A file you upload for one client (GSTR-2B, GSTR-1, GSTR-3B, IMS, registers, bank statements, AIS, TIS, Form 26AS, Tally Day Book) | Data imports, client page | Upload a client's return, register or statement |
| One zip with many clients' portal files | Data imports, Bulk upload | Upload many clients' portal files in one zip |
| Tally, read on a schedule by the connector on the firm's computer | Data imports, Tally connector | Read Tally books with the connector |
| A client's Zoho Books, read with the client's consent | Connected books | Connect a client's Zoho Books |
| Busy's own export files, uploaded or picked up from a folder | Connected books, Busy books | Import a client's Busy books |
Which file kinds your firm can upload, and the switches that turn some of them on, are listed in File kinds the importer reads.
What happens to a file
Steps
- Virus check. Nothing is opened before the malware scan passes.
- Recognise the format. The app picks a reader from the content, or uses the kind you chose.
- Read and check. Every row is checked (identifiers, dates, tax heads, totals). Problems are listed as errors, warnings or information, each pointing at the row or field.
- Publish. A file without errors is published as a new version of the dataset. A register with a few bad rows can be published partly, if you accept the valid rows.
Aadhaar numbers are masked before anything is stored, and passwords given for protected PDFs are used once and discarded. See Datasets, versions and the original file for versions, withdrawing and the original file.
Books going out
Export to books builds a Tally import file of the firm's own billing, which you import into the firm's Tally yourself: Export the firm's billing to Tally (sign in to read).
Settings and switches
Firm settings for connected books are in Settings for connected books and the books export (sign in to read). Some sources are switched on per firm while they are rolled out: bulk upload, the Tally connector, bank statements, AIS PDFs and JSON, trial balances, GSTR-1A, GSTR-9, and the e-invoice and e-way bill registers. A page whose source is off for your firm says so.
When something goes wrong
Each problem has its own help article, reached from the message. The most common are The file’s format could not be recognised (sign in to read), The GSTIN in the file is not one of this client’s GSTINs (sign in to read), The file is password-protected (sign in to read) and The client’s consent is required before its books are read (sign in to read). Documents the app builds for you (letters, certificates, packs) have their own problems: Documents the app builds, packs and signs.
Documents the app builds, packs and signs
Letters, certificates and reports are built from templates, combined into packs and signed by the app's document service; this explains each step and the problems each can report.
Several parts of the app produce documents for you, for example engagement letters, certificates, appeal paper books and certificate bundles. They all use the same document service, which also reads PDFs and spreadsheets for imports. It works only on the data sent to it and keeps nothing.
Build a document from a template
A template holds fixed text and placeholders; the app fills each placeholder from the record the document is about. Templates hold no logic, so the same data always gives the same document.
- A placeholder with no value: A value the template needs is missing (sign in to read).
- A template that is not valid: The document template is not valid (sign in to read).
Combine documents into a pack
A pack joins many documents (PDF, PNG, JPEG, Excel, Word or text) into one or more PDFs with a cover and index, split into parts of a maximum size when needed. Encrypted PDFs are never opened.
| Problem | See |
|---|---|
| An encrypted PDF | A document of the pack is an encrypted PDF (sign in to read) |
| A kind of file that cannot be packed | A document of the pack is of a kind that cannot be packed (sign in to read) |
| A damaged or unreadable document | A document of the pack could not be read (sign in to read) |
| A page larger than a part | One page is larger than the part size limit (sign in to read) |
| Too many parts | The pack needs more parts than allowed (sign in to read) |
| Too many pages | The pack has more pages than allowed (sign in to read) |
Sign a PDF with a DSC
Signing has two steps: the app prepares an empty signature place in a PDF it rendered itself, then embeds the signature your DSC makes. A PDF edited elsewhere, encrypted or already signed cannot be signed here.
- The PDF cannot take a signature (sign in to read)
- The signature place in the PDF is not usable (sign in to read)
- The signature does not fit the PDF (sign in to read)
Files that are too heavy
Each file is read with a time and memory limit, so a very large or damaged file can stop with The file is too large or complex to read (sign in to read).
Column mappings for registers and bank statements
Tell the importer which column of your register or bank statement holds each field, how dates are written and how amounts are signed; a mapping whose headers match a file is then used automatically.
Registers and bank statements come in many layouts. Files that follow the platform template, or whose headers the importer recognises, need no mapping. For any other layout, save a column mapping once; every later file with the same headers uses it automatically.
Everyone can see the mappings. Managers, partners and firm admins create, change and delete them.
Create a mapping
Steps
- Open Data imports, then Column mappings, and choose New mapping (or start from a template button).
- Give it a Name and say what it is For (a purchase or sales register, or a bank statement).
- Paste the file's header row, one header per line, exactly as the file prints them.
- Under Which column holds each field, pick the column for each field. Required fields must all be mapped.
- Say how Dates are written as (day, month, year such as 31-03-2026, or another order) and the Signs of amounts (positive with the document type giving the direction, or signed as in the books).
- Tick Use as the firm's default for this kind of file if most of your clients' files look like this, and save.
When you upload a register you can also pick a mapping by hand under Column mapping.
Example
A synthetic client's purchase register has headers "Bill No", "Bill Dt", "Party GSTIN", "Taxable Amt", "IGST", "CGST", "SGST". You map them to document number, document date, supplier GSTIN, taxable value and the three tax heads, and choose "Day, month, year".
Connect a client's Zoho Books
Record the client's consent, authorise read-only access in Zoho, choose the organisation, then sync. The firm reads the books and never writes to them; access tokens never reach the browser.
Connected books (/books) lists each client whose Zoho Books the firm reads, with its state,
organisation, consent end date and last sync. Connections that need attention are counted at the
top. Connections are read-only: nothing is ever written to the client's books.
Who can connect
Managers, partners and the owner start connections (confirming it is them). Recording a firm-held signed consent is for partners and the owner; managers too when the firm allows it (Settings for connected books and the books export (sign in to read)). Seniors and staff can run syncs.
Connect
Steps
- Choose Connect a client's Zoho Books and pick the client.
- Read What the firm will read: the plain list of what is read, and the consent text version.
- Choose how the client consents:
- The client signed a consent the firm holds: give the Consent document id of the signed consent stored in the client's documents (class "Books consent"); or
- Ask the client in the client portal: the client agrees and authorises there (Connect your Zoho Books for your CA team).
- Optionally set Consent valid until (the firm's default applies otherwise; there is an upper limit). Choose the Zoho data centre (India, zoho.in).
- Choose Record consent and connect, then Continue to Zoho, sign in with the client's Zoho account and allow read access.
- Back on the connection page, Choose the organisation. If its GSTIN is not one of the client's registrations, give a reason to map it anyway.
- Sync this financial year, or let the schedule run.
Connection states
| State | Meaning | What to do |
|---|---|---|
| Waiting for authorisation | Created, not yet authorised in Zoho | Authorise again |
| Waiting for the client's consent | Consent not yet given or attached | Attach a signed consent, or wait for the client |
| Connected | Syncs run | Nothing |
| Connected, with problems | Recent calls failed | See the last problem |
| Authorisation expired | Zoho no longer accepts the grant, or consent expired | Authorise again |
| Needs attention | An error stopped the connection | See the last problem, then authorise again |
| Disconnected | Revoked; what was read stays | Start a new connection if needed |
Disconnect… stops the firm reading the books; data already read stays.
The organisation panel
Once an organisation is chosen, its panel shows Sync runs (Books sync runs), a link to Group mapping (Group mapping for Zoho Books and Busy) and the Sync schedule (IST, cron). Leave the schedule empty to turn scheduled syncs off.
Connect your Zoho Books for your CA team
When your CA team asks to read your Zoho Books, read what they will see, agree, and allow read-only access in Zoho. You can disconnect at any time.
Your CA team can ask to read your Zoho Books, for example to prepare your returns. They can only read: nothing is changed in your books.
Steps
- Open Your books in the client portal. Requests from your CA team lists each open request.
- Open the request and read what your CA team will be able to read, and until when.
- Choose I agree, continue to Zoho, then Continue to Zoho to allow access.
- Sign in to Zoho with your own account and allow access.
- You return to Your books, which shows "Your Zoho Books is connected".
Disconnect
Under Connected books, choose Disconnect… next to the connection, then Disconnect now. You can also remove the access in Zoho. What your CA team has already read stays with them.
If it does not work
- "This request is no longer open": ask your CA team to send a new request.
- "That authorisation link has expired or was already used": open the request again and continue to Zoho without delay, in the same browser.
- "Access was not granted in Zoho": open the request again and allow access on Zoho's page.
Group mapping for Zoho Books and Busy
How Zoho account types and Busy account groups land in the books groups the firm's checks read, and how to override the standard map for one organisation or company.
Zoho Books and Busy classify accounts their own way. To read them like Tally books, the app maps each Zoho account type (or Busy account group) to a Group and its Primary group.
- The Standard map is reviewed platform content. A note says when a new version is still in review.
- Overrides apply to one Zoho organisation, or one Busy company, only. For Zoho an override can name an account type or a single account; for Busy, sub-groups follow their parent group.
An account type or group with no mapping is posted under Suspense A/c with a warning, so totals stay right and the reviewer sees the gap (An account type has no group mapping (sign in to read)).
Add an override
Steps
- Open the organisation from Connected books and choose Group mapping (for Busy, open the company from Busy books).
- Enter the Zoho account type or account (or the Busy group), the Group and the Primary group, and choose Add.
- Remove overrides you no longer need, then Save overrides.
Overrides apply from the next sync or import.
Example
A synthetic organisation uses the Zoho account type "other_current_liability" for advances from customers. You add an override mapping it to the group "Current Liabilities" with primary group "Current Liabilities".
Import a client's Busy books
Upload Busy's own XML or Excel export for a client; each export replaces the earlier version for its period, and the ledgers and vouchers then read like Tally books across the app.
Busy books imports a client's books from Busy's own export files. Busy's data files are never read. Each export covers a whole period and replaces the earlier version for it; after the checks the ledgers and vouchers read like Tally books everywhere in the app.
Export kinds
| Kind | What it holds |
|---|---|
| Busy XML export | Masters and vouchers from Busy's data export (preferred) |
| Busy's Tally-compatible XML | A fallback: voucher series and some GST details are not in this export |
| Busy Excel export | An accounts sheet and a day-book sheet (.xlsx or .xls) |
Import an export
Steps
- In Busy, export the masters and vouchers together for the whole period.
- Open Connected books, then Busy books, choose the client and the export kind.
- For an Excel export, a saved Column mapping is found automatically from the column titles; pick one if needed (Column mappings for registers and bank statements).
- Choose the file and import. The period comes from the export; without one, the financial year of its vouchers is used.
The first import creates the client's Busy company from the company named in the export; it is then listed under Busy companies of this client, with its group mapping.
Checks
Every voucher must balance, the export must hold the masters its vouchers name, and the ledger balances must agree. An export that fails is not published and the earlier version stays current. See The Busy export lacks masters or vouchers (sign in to read) and The trial balance does not agree with the ledgers (sign in to read).
To pick up exports automatically from a folder on a computer, see Agent watch folders for Busy exports (sign in to read).
Read Tally books with the connector
Pair the Tally connector on a computer that runs Tally, map each Tally company to its client, and the connector sends the books on a schedule. Passwords and Tally PINs are never sent.
The Tally connector is a small program installed on a computer that runs Tally. It reads the books of the companies you map and sends them to the app on a schedule. It is switched on per firm; when it is off you can still upload Tally Day Book XML files by hand (Upload a client's return, register or statement).
Who does what
- The owner, partners and firm admins pair and revoke connectors.
- Managers and partners map a Tally company to a client and set its schedule.
- Seniors, staff, managers and partners can ask for a sync of a mapped company.
Pair a computer
Steps
- Install the connector on the computer with Tally (Tally must allow connections on its port).
- In the app open Data imports, then Tally connector, and create a pairing code. You are asked to confirm it is you.
- Enter the code in the connector within 10 minutes. A code works once.
- The computer appears under Connectors with its health: degraded means Tally is closed or slow; down means no heartbeat for 15 minutes.
Map companies
The connector reports the companies open in Tally under Tally companies. Map each to its client and set the schedule. A company marked "Not mapped to a client" sends nothing.
How syncs work
Each sync reads what changed since the last one, using Tally's change counters, and is published as a new books dataset after the usual checks. If Tally's counters go back (for example after a restore from backup), a full resync of the period is queued by itself (Tally’s change counters went back; a full resync was queued (sign in to read)). If the number of vouchers read differs from Tally's own count, the sync is not published (The voucher count differs from Tally’s count (sign in to read)).
The same connector can watch folders for Busy export files: Agent watch folders for Busy exports (sign in to read).
Upload a client's return, register or statement
Find the client under Data imports, upload the file, and follow it through the virus check, reading and checks until it is published as a dataset.
Data imports (/imports) is where you bring a client's files into the app. What passes the
checks is published as a dataset that reconciliation and other work use.
Upload a file
Steps
- Open Data imports and find the client by name or code. The client's data page lists their Datasets and earlier Uploads.
- Choose Upload a file and pick the file.
- Under What is it? leave "Recognise it from the file", or choose the kind (for example GSTR-2B, a purchase or sales register, a bank statement, AIS, TIS or Form 26AS).
- For a register, say whether it is a purchase or a sales register, and give the Return period (month and year, such as 092026) and the GSTIN when the file does not say them. A saved Column mapping is used automatically when its headers match.
- For a password-protected AIS, TIS or Form 26AS PDF, enter the PDF password. It is used to read the file and then discarded.
- For a register, choose what happens If some rows have errors: use the firm's setting, let you accept the valid rows (when at most one row in five has errors), or reject the whole file.
- Choose Upload. The upload page opens and updates by itself.
Follow the upload
The upload page shows each stage: scanning for viruses, recognising the format, reading the file, checking the data and saving the dataset.
| What you see | What it means | What to do |
|---|---|---|
| Published | The data is a new dataset version | Open the dataset |
| Waiting for you to accept the valid rows | Some register rows have errors | Accept the valid rows (published as a partial dataset), or upload a corrected file |
| Rejected | Errors stopped publication | Read the Validation issues (or the error report), correct the file, upload again |
| Blocked by the virus scan | The file was flagged | Get a clean copy: The virus scan blocked the file (sign in to read) |
| Failed | The file could not be processed | The message names the reason |
| Identical to an earlier upload | Nothing new to publish | Open the earlier upload |
Validation issues can be filtered by severity. Errors stop a row (or the file); warnings and information are kept with the data for the reviewer.
Send a corrected file
When valid rows were accepted, choose Upload a corrected file on the upload. The corrected rows are added to the valid rows of the earlier upload and published together.
Cancel an upload
Seniors, staff, managers and above can cancel an upload before it is published. Articles can upload, view and accept, but not cancel.
Example
A synthetic client has two GSTINs. You upload a purchase register covering only the second one, choose GSTIN "27ABCDE••••F1Z5" in the dialog, and give return period 092026. Four of 200 rows have no place of supply. You accept the 196 valid rows now and upload the four corrected rows later as a corrected file.
Upload many clients' portal files in one zip
Upload one zip of up to 500 files from the GST or income-tax portals; each file is matched to its client by the GSTIN, PAN or TAN inside it and becomes that client's upload.
Bulk upload saves you opening each client when you have downloaded many portal files at once. It is switched on per firm; when it is off, the page says so and you upload from each client's page.
Steps
- Put the portal files (for example GSTR-2B JSON or Form 26AS) into one zip. Do not put a zip inside the zip; at most 500 files.
- Open Data imports, then Bulk upload, and upload the zip.
- The app scans the zip for viruses, then splits it. Each file is matched to a client by the GSTIN, PAN or TAN inside it, and only to clients you are allowed to edit.
- The bulk upload page lists Uploads created (one per file matched to a client) and Files not used, with the reason for each.
Each created upload then goes through the usual checks, like an upload made on the client's page (Upload a client's return, register or statement).
Files not used
| Reason | What to do |
|---|---|
| No client you can access has this registration | Add the registration to the client, or ask whoever handles that client: No client you can access has this registration (sign in to read) |
| The format could not be recognised | Check the file: The file’s format could not be recognised (sign in to read) |
| The archive is unsafe | Rebuild the zip: The archive is unsafe or unreadable (sign in to read) |
Books sync runs
What a sync run of a client's Zoho Books shows (status, step, period, calls used, records read) and what each status means, including pauses for Zoho's limits.
Each sync of a connected organisation is a sync run. The run page shows its status, kind, period, current step, the number of calls made to Zoho, when it resumes if paused, the problem if any, and the Records read by type. A published run links to the import batch this run produced, where the checks are listed.
Statuses
| Status | Meaning |
|---|---|
| Queued, Reading | The run is waiting or reading from Zoho |
| Paused (rate limit) | Zoho asked the app to slow down; the run resumes by itself |
| Paused (daily limit) | The firm's daily share of Zoho calls for this organisation is used; it resumes after midnight IST |
| Building the version | The books, ledgers and trial balance are being assembled and checked |
| Published | A new books version (and, by default, a trial balance) was published |
| No changes | Nothing changed since the last version |
| Rejected | A check failed (for example a voucher that does not balance); the earlier version stays current |
| Failed | The run stopped; the problem says why |
How much is read
The first sync of a newly mapped organisation reads the number of financial years set by the firm; later syncs read what changed. Now and then a run also sweeps for deleted records. The firm's settings (Settings for connected books and the books export (sign in to read)) control the first-sync years, the daily share of Zoho's call limit and whether a trial balance is published with each version.
Example
A synthetic organisation's first sync reads two financial years. Halfway, the run shows "Paused (daily limit)" and "Resumes" at 00:05 the next day; it then continues where it stopped and ends "Published".
Datasets, versions and the original file
A dataset is the published, read-only copy of a client's return, register, statement or books for a scope and period. Each new upload makes a new version; managers can withdraw one or download the original file with a reason.
A dataset holds the checked data of one kind for one client, registration (GSTIN, PAN or TAN) and period, for example the GSTR-2B of one GSTIN for September 2026. Datasets are read-only: to change the data, upload a corrected file.
What the dataset page shows
- Status: published (the current version), superseded (a newer version replaced it) or withdrawn.
- Partial: only the valid rows of the upload were accepted. Upload a corrected file to complete it.
- Versions: each publication for the same scope is a new version. The page says how many records were added, changed and removed since the previous one.
- Records: the rows as read, filterable by record type. Account numbers in bank statements are masked.
- The upload that produced the dataset, with its validation issues.
Reconciliations use the current version and record exactly which version they used. When a newer version is published, runs built on the old one are marked out of date and can be re-run (automatically if the firm's setting says so: Reconciliation settings and matching rules).
Withdraw a dataset
Managers, partners and the owner can Withdraw a dataset that should not be used, with a reason of at least 10 characters. Withdrawing is not deleting: the data stays for the record, is marked "do not use", and reconciliations built on it are invalidated.
Download the original or reveal an account number
The original file can hold unmasked data such as Aadhaar numbers, so only managers and above can Download the original (with a reason), and they confirm it is them first (Step-up). Revealing a masked bank account number works the same way. The reason and the action are recorded in the audit log.
Warning
A downloaded original leaves the app's protection. Keep it only as long as you need it.
File kinds the importer reads
The returns, registers, statements and books files Data imports can read, the form each must be in, and which kinds are switched on per firm while they are rolled out.
Each kind of file is read by its own reader. Download files from their official source and upload them unchanged: a file edited by hand often fails its checks.
Always available
| Kind | Form |
|---|---|
| GSTR-2B | JSON from the GST portal |
| GSTR-1 / IFF | JSON |
| GSTR-3B | JSON |
| IMS inward supplies | JSON |
| Purchase or sales register | Excel (.xlsx, .xls) or CSV, on the template or with a column mapping |
| AIS and TIS | CSV export |
| Form 26AS | TRACES text file |
| Tally Day Book | XML export |
Other modules add their own kinds (for example TDS statements and certificate bundles, or notices from the portals); they are offered on those modules' screens.
Switched on per firm
These kinds are turned on for a firm while they are rolled out. When one is off, an upload of that kind is refused with This kind of file or connection is not available (sign in to read).
| Kind | Switch |
|---|---|
| Bank statement (generic CSV) | ff.ingest.bank_statement |
| AIS, TIS and Form 26AS as PDF (the CSV and text exports are always available) | ff.ingest.ais_pdf |
| AIS as JSON | ff.ingest.ais_json |
| Trial balance on the platform template (Excel or CSV) | ff.ingest.trial_balance |
| GSTR-1A | ff.ingest.gstr1a |
| GSTR-9 (system-computed and filed) | ff.ingest.gstr9 |
| E-invoice register on the platform template (CSV) | ff.ingest.einv |
| E-way bill register on the platform template (CSV) | ff.ingest.ewb |
Bulk upload and the Tally connector are switched the same way: Upload many clients' portal files in one zip, Read Tally books with the connector.
Password-protected PDFs
AIS, TIS and Form 26AS PDFs are often protected. Enter the password in the upload dialog; it is used once to read the file and then discarded.