Skip to content

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

SourceWhereRead 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 pageUpload a client's return, register or statement
One zip with many clients' portal filesData imports, Bulk uploadUpload many clients' portal files in one zip
Tally, read on a schedule by the connector on the firm's computerData imports, Tally connectorRead Tally books with the connector
A client's Zoho Books, read with the client's consentConnected booksConnect a client's Zoho Books
Busy's own export files, uploaded or picked up from a folderConnected books, Busy booksImport 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

  1. Virus check. Nothing is opened before the malware scan passes.
  2. Recognise the format. The app picks a reader from the content, or uses the kind you chose.
  3. 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.
  4. 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: .

Settings and switches

Firm settings for connected books are in . 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 , , and . 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.

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.

ProblemSee
An encrypted PDF
A kind of file that cannot be packed
A damaged or unreadable document
A page larger than a part
Too many parts
Too many pages

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.

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 .

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

  1. Open Data imports, then Column mappings, and choose New mapping (or start from a template button).
  2. Give it a Name and say what it is For (a purchase or sales register, or a bank statement).
  3. Paste the file's header row, one header per line, exactly as the file prints them.
  4. Under Which column holds each field, pick the column for each field. Required fields must all be mapped.
  5. 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).
  6. 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 (). Seniors and staff can run syncs.

Connect

Steps

  1. Choose Connect a client's Zoho Books and pick the client.
  2. Read What the firm will read: the plain list of what is read, and the consent text version.
  3. 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).
  4. Optionally set Consent valid until (the firm's default applies otherwise; there is an upper limit). Choose the Zoho data centre (India, zoho.in).
  5. Choose Record consent and connect, then Continue to Zoho, sign in with the client's Zoho account and allow read access.
  6. 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.
  7. Sync this financial year, or let the schedule run.

Connection states

StateMeaningWhat to do
Waiting for authorisationCreated, not yet authorised in ZohoAuthorise again
Waiting for the client's consentConsent not yet given or attachedAttach a signed consent, or wait for the client
ConnectedSyncs runNothing
Connected, with problemsRecent calls failedSee the last problem
Authorisation expiredZoho no longer accepts the grant, or consent expiredAuthorise again
Needs attentionAn error stopped the connectionSee the last problem, then authorise again
DisconnectedRevoked; what was read staysStart 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

  1. Open Your books in the client portal. Requests from your CA team lists each open request.
  2. Open the request and read what your CA team will be able to read, and until when.
  3. Choose I agree, continue to Zoho, then Continue to Zoho to allow access.
  4. Sign in to Zoho with your own account and allow access.
  5. 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 ().

Add an override

Steps

  1. Open the organisation from Connected books and choose Group mapping (for Busy, open the company from Busy books).
  2. Enter the Zoho account type or account (or the Busy group), the Group and the Primary group, and choose Add.
  3. 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

KindWhat it holds
Busy XML exportMasters and vouchers from Busy's data export (preferred)
Busy's Tally-compatible XMLA fallback: voucher series and some GST details are not in this export
Busy Excel exportAn accounts sheet and a day-book sheet (.xlsx or .xls)

Import an export

Steps

  1. In Busy, export the masters and vouchers together for the whole period.
  2. Open Connected books, then Busy books, choose the client and the export kind.
  3. 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).
  4. 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 and .

To pick up exports automatically from a folder on a computer, see .

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

  1. Install the connector on the computer with Tally (Tally must allow connections on its port).
  2. In the app open Data imports, then Tally connector, and create a pairing code. You are asked to confirm it is you.
  3. Enter the code in the connector within 10 minutes. A code works once.
  4. 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 (). If the number of vouchers read differs from Tally's own count, the sync is not published ().

The same connector can watch folders for Busy export files: .

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

  1. Open Data imports and find the client by name or code. The client's data page lists their Datasets and earlier Uploads.
  2. Choose Upload a file and pick the file.
  3. 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).
  4. 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.
  5. For a password-protected AIS, TIS or Form 26AS PDF, enter the PDF password. It is used to read the file and then discarded.
  6. 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.
  7. 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 seeWhat it meansWhat to do
PublishedThe data is a new dataset versionOpen the dataset
Waiting for you to accept the valid rowsSome register rows have errorsAccept the valid rows (published as a partial dataset), or upload a corrected file
RejectedErrors stopped publicationRead the Validation issues (or the error report), correct the file, upload again
Blocked by the virus scanThe file was flaggedGet a clean copy:
FailedThe file could not be processedThe message names the reason
Identical to an earlier uploadNothing new to publishOpen 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

  1. 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.
  2. Open Data imports, then Bulk upload, and upload the zip.
  3. 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.
  4. 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

ReasonWhat to do
No client you can access has this registrationAdd the registration to the client, or ask whoever handles that client:
The format could not be recognisedCheck the file:
The archive is unsafeRebuild the zip:

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

StatusMeaning
Queued, ReadingThe 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 versionThe books, ledgers and trial balance are being assembled and checked
PublishedA new books version (and, by default, a trial balance) was published
No changesNothing changed since the last version
RejectedA check failed (for example a voucher that does not balance); the earlier version stays current
FailedThe 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 () 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

KindForm
GSTR-2BJSON from the GST portal
GSTR-1 / IFFJSON
GSTR-3BJSON
IMS inward suppliesJSON
Purchase or sales registerExcel (.xlsx, .xls) or CSV, on the template or with a column mapping
AIS and TISCSV export
Form 26ASTRACES text file
Tally Day BookXML 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 .

KindSwitch
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 JSONff.ingest.ais_json
Trial balance on the platform template (Excel or CSV)ff.ingest.trial_balance
GSTR-1Aff.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.