schedule-iii

Record your user’s assertion that the previous year genuinely had no activity, so this statement’s all-nil previous-year Profit and Loss is a fact rather than a closing-entry artefact. This clears Datavrn’s refusal to finalise it. THIS IS A PROFESSIONAL ASSERTION ABOUT A CLIENT’S ACCOUNTS, RECORDED IN THE NAMED MEMBER’S NAME AND KEPT WITH THE STATEMENT. Only send it when your user has told you, in their own words, that the previous year had no activity — a dormant entity is the case it is for. NEVER write the reason yourself and never paraphrase it into something firmer: send what they said. If they are unsure, or if the previous year DID trade and the trial balance was simply taken after closing, do not call this — the other two remedies in get_comparative_source_state are the correct ones. Call get_comparative_source_state first, read out the finding, get their explicit go-ahead, and send the confirm_token it returned. Datavrn refuses if the previous-year figures changed after you read the state, and nothing is recorded. It can be withdrawn in Datavrn if it was recorded in error; withdrawing restores the refusal.

Record your user’s confirmation that they have REVIEWED a whole section and it is complete — the entire previous-year comparative column, or the entire disclosure set. A review confirmation is your user’s professional assertion, recorded as authorised by them. Before calling this, show them what you are confirming — the whole comparative, or the whole disclosure set — and get their explicit go-ahead. Never confirm a review that has not happened. Saving figures or text does NOT complete these two sections and never has; only this confirmation does. The confirmation is pinned to the exact set that was reviewed, so ANY later save to that section withdraws it — if a confirmation appears not to stick, the next step is to re-review and confirm again, never to retry. Confirming again after such a change supersedes the earlier confirmation: it is marked withdrawn (it stays on the record) and the response names what was withdrawn. Re-confirming also invalidates any finalise approval you already hold. Only two sections take a review confirmation: the previous-year comparative and the disclosure set. Every other section is answered by saving its rows, or by declare_capture_na. Datavrn notifies the member you name that this was recorded in their name. Generate a fresh version after your last capture change — finalisation checks the version’s frozen capture state, not today’s.

Persist only the explicit account-to-centre decisions the user approved. Before calling, show the proposal grouped by confidence tier and target with exact counts, call out every medium/low-confidence row, and get a clear approval for the enumerated items. Omitted accounts stay unchanged; there is no apply-all, auto-confirm, or use-suggestions flag. Each item writes ONE dimension, chosen by target_type: "cost_centre" writes the cost-centre policy and "profit_centre" writes the profit-centre policy. The two are independent — writing one never replaces the other — and the same account may appear once per dimension in a single call. A centre policy can only be set on a profit-and-loss account: an account Datavrn resolves to a balance-sheet type, or has not classified yet, is refused by name and nothing is saved. After the write, report confirmed, unmapped_total and unmapped_with_balance (the cost dimension), and profit_unmapped_total and profit_unmapped_with_balance (the profit dimension) so the user knows exactly what remains. When profit_centres_total is 0 the profit dimension is not in use and no account needs a profit-centre policy — never report the entity as profit-mapped. Read profit_mapped_total beside it: 0 means no account holds one, and above 0 means the dimension has been closed while that many accounts still carry a saved policy pointing at a deactivated centre. The counts describe the policies in force on counts_as_of. A write can be saved and still not be in force, in two ways, and next_action says which: effective_from later than counts_as_of (not in force yet), or superseded_total above 0 (that many of these accounts already carry a LATER version that is in force, so this back-dated write changes nothing visible). In either case do not repeat the call. This tool never returns rupee amounts.

Confirm the column→field mapping for a staged upload and run validation. Returns the full validation result (row counts, warnings, blocking issues). Mapping suggestions are never auto-applied — pass exactly the mapping your user approved. Review any warnings with your user before ingesting.

Record your user’s explicit confirmation that one upload is an entity’s COMPLETE CURRENT chart of accounts, so Datavrn starts treating it as evidence when checking whether future files belong to that entity. Recorded as authorised by the member you name. THIS IS A PROFESSIONAL JUDGMENT, NOT A CALCULATION. Datavrn will never make it from the numbers, and neither should you: call preview_chart_rebaseline for that upload first, read its counts to your user, and ask them plainly whether that upload is the entity’s whole book now. Confirming a file that is NOT the entity’s chart teaches Datavrn the wrong chart and weakens wrong-entity detection for that entity from then on. Send back the state_digest and confirm_token from the SAME preview_chart_rebaseline response, unchanged. Datavrn refuses and changes nothing if: the entity’s uploads moved after you were shown those figures, someone already confirmed this upload, the upload no longer needs confirming, or it is one Datavrn asked about directly — for those, answering that question is what settles it. Nothing about the landed figures changes: this affects only which uploads count as evidence of identity.

Persist USER-approved account→line groupings. Omitted accounts stay unchanged. Only explicit leaf_code:null clears a saved grouping. When clearing a saved grouping, use the current grouping_version from list_grouping_suggestions. An actual clear first returns an approval request; nothing changes then. Resend the unchanged request with the approval details to proceed. Clearing an already-unclassified account is an idempotent no-op. Every row must be explicit — there is deliberately no "apply all suggestions" option.

Persist only the explicit reporting-line decisions the user approved. Before calling, show the proposal grouped by confidence tier and target with exact counts, flag every medium/low-confidence row, and get clear approval for the enumerated decisions. Omitted accounts stay unchanged. Sending leaf_code:null permanently removes that account saved reporting line; send it only when the user explicitly asked to clear that row. There is no apply-all or auto-confirm flag. The response tells you how many were confirmed, cleared, and whether the balance-bearing set is fully mapped; never claim completion without checking those fields.

Copy the previous period’s "nothing this period" and "does not apply" answers into this period, for sections that have no answer yet. It NEVER copies a review confirmation — a review is about this period’s content and cannot be inherited. Last period’s answer is not evidence about this period: list what it would copy to your user, section by section, and get their go-ahead before calling it. Answers already recorded for this period are left alone. Generate a fresh version after your last capture change — finalisation checks the version’s frozen capture state, not today’s.

Create a new entity (company) in the organization. Requires a Manager-role key. Use only when the user explicitly asks to set up a new entity; show them the name you will create first.

Create one cost centre for an entity after showing the user the exact name, kind, parent, effective date, and reason. This is one explicit centre at a time; there is no apply-all shortcut. After creating it, call list_cost_centres again and explain which mapping suggestions can now use it.

Create one profit centre for an entity after showing the user the exact name, optional parent, and description. This is one explicit centre at a time; there is no apply-all shortcut. Re-list the centres after creation so the user can see the new target before any mapping confirmation.

Mint a single-use, login-free upload link so a file reaches Datavrn WITHOUT passing through your context, where it cannot truncate or corrupt. Use this whenever a human has the file (a trial balance export, etc.) — and also whenever YOU hold the file and it is larger than about 10 KB. This is the RELIABLE path at that size: inlined base64 mutates often enough that the damage arrives as a plausible-looking trial balance rather than an obvious error, while the link delivers the bytes byte-perfect. Two ways to deliver the file: a HUMAN opens upload_url in their browser and chooses the file; a PROGRAMMATIC caller that already holds the file on disk POSTs it to the SEPARATE upload_post_url as a multipart form with a single `file` field (upload_url is the human page and will not accept a POST). The POST reply carries received_file_hash — compare it to your local sha256 before confirming the mapping. The link stages the file for ONE entity and expires in about 15 minutes; nothing is ingested until the column mapping is confirmed.

Record that a capture section had NOTHING to report this period, DOES NOT APPLY to this entity, or that this is the entity’s FIRST YEAR (previous-year figures only). These are three different statements and are not interchangeable: "nothing this period" means the section applies but had no activity; "does not apply" means it never applies to this entity at all. This is your user’s professional assertion, recorded as authorised by them — ask which one is true, and never guess. NOT every reason is available for every section — call get_schedule3_workspace and read allowed_reason_codes on the section before you ask your user, so you never put a choice to them that Datavrn will refuse. The restrictions: Settings takes NO answer here at all (it is only answered by saving the settings); share capital and partner capital take only "nothing this period", because those sections are shown only for statement formats they apply to, so "does not apply" can never be true; and "first year" belongs only to previous-year figures. To record a REVIEW being complete (previous-year figures, disclosures) use confirm_capture_review instead; this tool cannot make that assertion. A section can only hold one active answer. If the section’s current answer is still standing, this call refuses — revoke it with revoke_capture_declaration first. If the current answer was already WITHDRAWN by later changes (Datavrn shows the section as unanswered), this call supersedes it: the old answer is marked withdrawn and stays on the record, and the response names what was withdrawn. An answer is never edited in place. Superseding or changing an answer invalidates any finalise approval you already hold — the next finalise_statement will ask you to review the current state again. Generate a fresh version after your last capture change — finalisation checks the version’s frozen capture state, not today’s.

Seal a statement version as Datavrn’s permanent client copy, recorded as authorised by the member you name. THIS IS NOT APPROVAL OR ADOPTION OF THE FINANCIAL STATEMENTS AND IT IS NOT A SIGNATURE. It does not discharge section 134(1) for a company or section 34(3) for an LLP. THERE IS NO UNDO. A change afterwards means generating a new version and finalising that one; the version you seal here stays sealed. Call get_finalise_readiness first, show your user every gate and every warning it returns, get their explicit go-ahead, and only then send the confirm_token it gave you together with the acknowledgements. Never acknowledge a warning your user has not seen, and never write the acceptance reason yourself — it is their professional judgment in their own words. Datavrn will refuse if anything about the statement changed after you read the state, and nothing will be finalised. If the response comes back with reused set to true, a finalisation of this same version was already under way: nothing new was done and your approval was not used. Do not call finalise_statement again — the status field says where that finalisation is (queued, running, or paused, which means it hit a temporary problem and Datavrn will retry it on its own). Poll get_job with the job_id and tell your user what it says.

Queue the Schedule III workbook build (returns a job_id to poll with get_job — the build runs as a background job). REFUSES when ungrouped accounts exist unless acknowledged: before acknowledging, present the ungrouped accounts to your user and obtain their explicit go-ahead; record it in acknowledge_reason and pass the exact count in acknowledge_count — an acknowledgement WITHOUT its count is always re-demanded. A multi-month statement period additionally requires acknowledge_multi_month_pnl WITH acknowledge_month_count (confirm with your user that the TBs are period movements, not cumulative). Never acknowledge anything the user has not seen. Once queued, the build usually completes in a few minutes — tell your user their statements are being prepared and poll get_job periodically; do not present the wait as a problem.

MANAGEMENT data class. Read one explicit cost or profit partition of the current persisted allocation run at account grain. Cost-centre and profit-centre reconciliations are independent views of the same P&L activity; do not add them. Books figure plus spreading adjustment equals MIS figure, all as decimal-string rupees. Filter account names or minimum absolute MIS amount before paging. The signed page_token is source-pinned, so restart at page 1 if source_changed. known_stale and not_assessed disclose run state; neither means fresh.

MANAGEMENT data class. Read one explicit cost or profit partition of the current persisted allocation run at account × target × source × mode grain, with decimal-string allocated amounts. Cost-centre and profit-centre reconciliations are independent views of the same P&L activity; do not add them. Final post-step-down cost uses the complete selected cost population: non-step-down plus signed step-down. Filter allocation_sources=['step_down'] only to inspect transfers and confirm their run net is zero. Accounted equals assigned plus Unallocated; Unallocated is not additional. For profit centres, choose profit. Use filters before paging; the signed page_token is source-pinned, so restart at page 1 if source_changed. Target labels use the current governed centre timeline evaluated at the run period (target_labels_frozen: false); persisted allocation amounts stay unchanged. A controlled in-period centre correction changes a displayed label and invalidates the page token; restart at page 1 without regenerating allocation. Review run staleness and methodology, and regenerate when either changed. An integrity failure means regenerate, retry, then contact support if it recurs. No owners, descriptions, source transactions, or recomputation are returned.

MANAGEMENT data class. Read one versioned budget: identity-free header, its pinned P&L tree, and filtered/paginated cells with entered-versus-inferred truth. Amounts and locked FX rate are decimal strings. Filter months, lines, centres, or inference before paging; the signed page_token is source-pinned, so restart at page 1 if source_changed. Cells across different P&L lines are not one meaningful grand total, so no cross-line grand total is exposed. No people, ownership, editability, or approval identities are returned.

Check whether this statement’s previous-year comparative can be sealed, and get the approval assert_previous_year_no_activity needs. Datavrn refuses to finalise a statement whose previous-year figures come from a trial balance drawn AFTER the year-end closing entries: that derives a previous-year Profit and Loss of all zeroes which foots perfectly and is not last year’s results. When post_closing_detected is true, READ THE WHOLE finding TO YOUR USER — what the state is and all three ways out — and let them choose. Never choose for them. Two of the three remedies are things only they can do (upload the pre-closing trial balance, or enter last year’s signed figures as previous-year values, then generate a fresh version). The third is an assertion that the previous year genuinely had NO ACTIVITY, which is a statement about their client’s accounts, in their words, recorded in their name — a dormant company is the case it exists for. The approval is single-use, expires in 15 minutes, and is tied to this statement, this connection and the member you name; if the previous-year figures change in between, the assertion will be refused and you start again from here. If nothing is wrong there is no approval to hand back, because there is nothing to assert.

CONSOLIDATED data class. Read one sealed group profit-and-loss, balance-sheet, or cash-flow face for an exact periodicity and period. The response exposes presentation currency and exactly one decimal-string amount per line: section-natural for P&L/BS, signed cash movement for CFS. Amounts are persisted on the sealed run; P&L/BS labels are current display metadata and the signed page_token is source-fingerprinted across the complete safe face, so a changed value or label requires restarting at page 1. A stale sealed run is disclosed on every page and is never called current. Member names, components, eliminations, journal references and lineage are not returned. QUALIFICATIONS. A response may carry `owned_share_capital_caveat` (at seal, share capital owned by the group could not be eliminated, so those amounts remained inside consolidated share capital as the engine computed it; the DISPLAYED line may differ in either direction where a manual journal also moved it, so never characterise the direction from this field alone) and always carries `domestic_cash_flow_caveat`. These qualify specific statement lines. When a caveat is present, any figure it qualifies MUST be presented together with its qualification — never the number alone. `owned_share_capital_caveat` is null when the run was read and carries no such qualification, and `{status: "unavailable"}` when the run’s qualification record could not be read at all, which is not the same as clean: say so rather than presenting the figures as final. WITHHELD CASH FLOW. `cash_flow_status` may say the cash flow was not presented — for a group with a foreign member, or for a window with no opening balance sheet to measure from. An empty `cash_flow` then means the statement was WITHHELD, never that the group had no cash movements: say so. For the missing-opening-basis case `cash_flow_refusal` carries the cause, the message and `remedies`, each tagged with the channel that can perform it — `agent_or_app` you can do here, `app_only` needs a person in the Datavrn app. Never present an app_only remedy as something you will do. `cash_flow_opening_basis` states what a PRESENTED statement measured from; "not_recorded" means the run was sealed before Datavrn recorded that, so its basis is unknown — do not assume a prior period. ROW ROLES. Every statement row carries `row_role`: "line" participates in its section total, "total" restates it (Profit after tax), "attribution" splits a total (the amounts attributable to the owners and to the minority interest). To total a section, sum ONLY rows whose row_role is "line" — including a total or attribution row would double-count the group’s profit. Present the attribution rows as the split of profit after tax, never as additional income. Consolidated cash-flow is available only for an all-domestic group in v1. If any member uses a foreign currency, Datavrn does not present a consolidated cash-flow statement. Where it is presented, it is prepared by the indirect method from balance-sheet movements rather than from cash records, and classified into operating, investing and financing activities using each entity’s reporting-line mapping. Interest paid and taxes paid are not disclosed separately, so they remain inside the operating movement; a movement whose reporting line carries no cash classification is shown under “Unclassified movements — review” rather than assigned to an activity. Datavrn does not present other comprehensive income or total comprehensive income in the consolidated output.

Read the full finalisation state of one statement version, and get the approval finalise_statement needs. Call it ONCE immediately before finalising — it re-reads the stored workbook, so do not poll it. SHOW YOUR USER EVERY ROW THIS RETURNS — the gates that must be green, each warning they would be accepting and why, how many input cells are still empty, any control that could not be evaluated, and capture_live_diverged_message when it is present — before you finalise. Do not summarise the warnings away. capture_live_diverged_message means a capture answer changed after this version was generated: the version can still be sealed as it stands, and generating a fresh one is the alternative. Read it out and let your user choose. A control that "could not be evaluated" is not a pass: it is a check Datavrn did not run, and your user is entitled to know what was not checked before they seal the version. The approval is single-use, expires in 15 minutes, and is tied to this exact version, this connection and the member you name — if anything about the statement changes in between, finalise_statement will refuse and you start again from here. If your connection is not permitted to finalise, you still get the whole state; there is simply no approval to hand back.

Get the Datavrn agent guide: how connecting works (OAuth and API key), what an assistant can do, how reading a statement as data works, and the guarantees and limits — plus the current list of tools. Call this to answer a user's questions about how Datavrn works from canonical documentation instead of guessing.

Poll a background job by id until status is succeeded or failed. A failed job carries its user-safe error reason — show it to your user. Jobs run on a background worker that claims queued work on a schedule, so a job sitting at "queued" (0 attempts) for the first few minutes is NORMAL, not a fault — keep polling every ~30–60s and reassure the user it is being prepared; do NOT report this as an error or a Datavrn bug. Only if it is still "queued" well past a few minutes should you tell the user it is taking longer than usual.

Read the partner or owner capital schedule currently on file — Note 3a and Note 3b. THIS RETURNS PEOPLE’S NAMES, along with each person’s profit-sharing ratio and amounts. Call it before save_partner_capital so you can show your user what is on file and what your change would do — that save replaces the whole section, so a schedule you cannot see is a schedule you cannot safely replace. It also returns the total of the capital-account profit-sharing ratios, because Datavrn warns about a total that is not 100% only when at least two rows carry a ratio.

Answer "what's left to do?" across every entity you can see — one row per entity, with what is blocking its Schedule III statement: whether the trial balance is in, how many accounts are still ungrouped, the latest generated version, and whether it has been finalised. Pass period_label to pick a period, or omit to default to the period most of your entities have a trial balance for (not necessarily the newest — one entity uploading a future period early will not flip the board). Rows include deep links that open the Datavrn web app (a login is needed there). It also answers a second question nothing else here does: restorable_replacements lists automatic connector syncs that REPLACED an entity's data and can still be undone, soonest-closing first, each with the date its 30-day undo window shuts — after that the replaced data cannot be put back, and no message ever announces that clock running out, so raise these with your user rather than waiting to be asked (use list_replacements and preview_replacement_restore on the ids given; restorable_replacements_omitted says how many more were not listed).

THE state tool: grouping progress, every required capture answer, generated/finalised versions, finalisation blockers, and bounded per-version control summaries. Report generation never marks capture complete. Exception output is rule/severity/count only — no account names or amounts. Call this to know what is left before finalising.

Answer "how do I get started?", "what do I do next?", or help a user who seems lost setting up. Returns where they are in the journey from an empty organization to a finished Schedule III statement, and the ONE next step to take. Call it WITHOUT client_id first (the organization view): it lists the entities this credential can see, or — if there are none — the step to create the first one. Then call it again WITH one entity’s client_id for that entity’s full step-by-step path (upload trial balance → confirm groupings → capture figures → generate → download). Each step has a status (done / next / todo / blocked / web_only) and either the exact tool to call or a web-app link. NARRATE ONE STEP AT A TIME — walk the user through the single `next` step; do not dump the whole list unprompted. Steps marked web_only are done in the Datavrn web app and need a login — never claim you can do them yourself. This tool reports STATUS only (counts, names, what is done) — it never returns a figure or balance; read those with get_statement_figures once a statement is generated.

MANAGEMENT data class. Read the persisted books-to-MIS spreading reconciliation, not a new allocation run. Accounts view gives account-grain books plus adjustments equals MIS; adjustments view requires one account and pages its rule adjustments. Money is decimal-string rupees. Whole-run summary figures never change with account filters. The signed page_token is source-pinned, so restart at page 1 if source_changed. Raw warning context is withheld; known_stale and not_assessed are disclosure states, not freshness claims.

Read a generated Schedule III statement's figures: the balance-sheet and profit-and-loss faces, current-year and previous-year balance-sheet tie verdicts separately (a null verdict means UNKNOWN, never a pass: either no comparative was captured, or the version predates per-column balance recording), the unclassified count, and the notes listed by number. Also returns bounded exception counts by rule/severity and the frozen control changes versus the immediately previous recorded version; it never recomputes either from live books. Figures come from a generated version (the latest unless you pass a specific version) and match the workbook exactly. If the version was generated before figure reads existed it returns available:false with reason "figures_not_available" and only the legacy flat tie verdict; tell the user to generate the statement again, read the latest version, then retry. For a note's line-by-line breakdown, use its note_index entry with get_statement_notes. Amounts are decimal strings in rupees. ONE EXCEPTION: the profit-and-loss face ends with the statutory earnings-per-share rows, marked kind:"eps". Their figures are ₹ PER SHARE, not rupees of profit — report them as EPS and never add them into a face total. They are null until the weighted average share counts are saved in statement settings. Figures are Datavrn's deterministic engine output; interpretation is your assistant's.

Read the line-by-line breakdown of a generated statement's notes — every line's current and prior-year amount, and the note total. Pass note_numbers (from get_statement_figures' note_index) to fetch specific notes, or omit for all. Use this to answer "what's in Other Expenses?" or "what makes up trade receivables?". Each line has a kind: 'component' (an additive line), 'subtotal' (a presentational group subtotal — do NOT add it into the total, or you double-count), or 'header'. Fixed-asset / intangible notes carry a `block` per class with gross_block, accumulated depreciation, and net (the additions/deletions movement schedule itself lives in the workbook). If the full set is too large it returns too_large:true with a note_index — fetch note_numbers in small batches. A single very large note (e.g. a PPE schedule or an ageing note) is returned in explicitly-flagged line pages: each page carries the authoritative note total, lines_page, lines_total, and has_more_lines — keep fetching lines_page until has_more_lines is false; never treat one page's lines as the whole note. Amounts are decimal strings in rupees. Figures are Datavrn's deterministic engine output; interpretation is your assistant's.

Read the SOURCE DATA behind a statement: the trial-balance rows (account name, debit, credit) as landed for a period, BEFORE grouping — the pre-statement numbers, not statement figures. PREFER FILTERS over fetching everything: name_patterns (e.g. ['cash','bank','od']), side ('debit'/'credit' by net balance), and min_abs_balance return a small exact subset with its own debit/credit totals — e.g. wrong-side cash accounts = name_patterns ['cash','bank'] + side 'credit'. Paginated (page 1-based; page_size default 50, max 500). These are the CURRENT live rows: statement figures are frozen at a generated version, so if the trial balance was re-uploaded after a version was generated, these rows may not tie to that version (the response `note` says so). Amounts are decimal strings in rupees. Figures are Datavrn's deterministic engine output; interpretation is your assistant's.

Read an upload session: status, detected header row and columns, the confirmed mapping (if any), and the stored validation outcome. Use to check what a staged upload still needs.

Check an upload link's state: pending (the user has not uploaded yet), uploaded (returns the upload_id — continue with get_upload), or expired (mint a fresh link with create_upload_link). Poll after the user says they uploaded the file.

MANAGEMENT data class. Read the existing budget-or-prior variance report for a month; it never recalculates it. Amounts are decimal strings; a null actual or variance means unavailable, never zero. Rows view has whole-report unfiltered rollups and no cross-side grand total; filters affect only rows and filtered grain counts. Explanations view withholds internal notes and may redact structured PII. Filter lines or centres before paging; the signed page_token is source-pinned, so restart at page 1 if source_changed.

Mint a short-lived signed URL for a frozen workbook version (the Excel file). Give the URL to your user to open in a browser — it needs no login and expires in about 10 minutes. The bytes are immutable and integrity-hashed.

Commit a validated upload into the entity’s books. This is a TWO-CALL approval: if the upload has any warnings, or would permanently delete existing trial-balance rows for a period it covers, the first call writes NOTHING and refuses with every warning, the exact record counts, and a short-lived removal_token. Show your user every warning and both counts, get their explicit go-ahead, then resend the SAME call adding removal_token and removal_count exactly as returned. acknowledge_warnings is IGNORED on this connection — the token is the only acknowledgment, so sending it changes nothing. A clean, additive ingest needs no token and succeeds on the first call. Returns the ingestion outcome including any notices.

Review account-to-centre mapping status and deterministic suggestions for an entity. Each account carries TWO independent policies: mapping (the cost-centre policy) and profit_mapping (the profit-centre policy). Neither replaces the other. This is status-only: it returns account names, types, target names, confidence, reasons, and balance-bearing booleans, but never debit, credit, balance, or any rupee amount. Always present the rows grouped by confidence tier and target, state exact counts, flag every medium/low-confidence row, and show the completion counts: unmapped_total and unmapped_with_balance are the COST dimension (summary.scope says so), and profit_unmapped_total and profit_unmapped_with_balance are the profit dimension. Never add the two dimensions together, and never call an entity fully mapped on the cost counts alone. Do not call any count pending. Suggestions exist for the cost dimension only: suggestion_groups never describes profit work, and each row’s centre_suggestion carries dimension "cost" — never present it as an answer to a profit-centre question. A row carrying mapping_targets_inactive is confirmed onto a cost centre that has since been DEACTIVATED, and a row carrying profit_mapping_targets_inactive is the same fact on the profit dimension: those target ids are absent from the centres and profit_centres lists because they are no longer valid targets. Report summary.mappings_with_inactive_target (which counts an account with a dead target on EITHER dimension) alongside the completion counts and never describe such an account as settled. profit_centres_total says which zero a zero profit count is, and profit_mapped_total says what survives: when profit_centres_total is 0 the profit dimension is not in use and no account NEEDS a profit-centre policy — say that, never that the profit dimension is complete. If profit_mapped_total is also 0, no account has one either; if it is above 0 the dimension has been CLOSED and that many accounts still carry a saved policy pointing at a deactivated centre, which you must report rather than calling the entity profit-mapped.

MANAGEMENT data class. Discover persisted allocation runs and their separate cost-centre and profit-centre reconciliations; do not add them together. This does not generate or recompute allocation. Money is decimal-string rupees. Choose one allocation_dimension in a detail read. Results are ordered period, version, then run id, and the signed page_token is pinned to the complete filtered source: if it reports source_changed, restart at page 1. current_only means latest generated version, not source freshness; known_stale and not_assessed are both warnings, never a claim that the source is fresh. Raw stale reasons and warning context are not returned.

MANAGEMENT data class. Discover budget ids and versions without identity fields. Locked FX rate and all money-valued fields are decimal strings. Filter status or fiscal-year start before paging. The signed page_token is pinned to the complete filtered source; restart at page 1 if source_changed. This lists budget headers only, not cells, approvals identities, or a recalculated budget.

List the uploads Datavrn is NOT counting as evidence of which entity a file belongs to. This happens when an entity’s chart of accounts grew or changed faster than Datavrn can vouch for from what it already holds — typically an acquisition, a migration, or a year-end restructure. NOTHING WAS REJECTED, BLOCKED OR CHANGED: the figures in those uploads are landed and live. What has not advanced is the evidence Datavrn compares FUTURE uploads against, so wrong-entity detection for this entity is working from a smaller picture than the entity’s real chart. Each row reports how many distinctive ledger names Datavrn already held (trusted_considered), how many the upload carries (incoming_considered), how many are on both sides (matched), and the two coverage ratios. Show your user those numbers in their own terms. `shortfall` names WHICH direction fell short, and it is the part to say out loud, because the three cases are different situations to an accountant: "incoming" means most of the file is ledger names Datavrn does not already treat as evidence — the chart in the file is much larger than what Datavrn holds; "trusted" means much of what Datavrn holds is missing from the file; "both" means the two charts barely overlap either way. It is null when there was nothing to compare against at all, which the row reports as reason "empty_trust_recovery". This call only lists. To confirm one of these uploads, call preview_chart_rebaseline for that upload — it re-reads the figures and issues the approval confirm_complete_chart needs. An empty list means nothing is waiting: for almost every entity that is the normal state.

List the entities (companies) this credential can work with. Call this first to resolve the client_id every other tool needs. Returns each entity id and name.

List the cost centres for an entity. Use this before proposing account mappings so you can group the proposal by target name and distinguish operating from support centres. This is status-only: it returns names, short codes, kinds and each centre’s parent_cost_centre_id, never rupee amounts and never an owner’s name. Read parent_cost_centre_id (null at the top level) to show the user the hierarchy that create_cost_centre wrote, so a wrong parent can be seen and corrected. is_active false means the centre is DEACTIVATED: it is not an available target, never propose a mapping onto one, and never count it when you tell the user how many targets exist. Check the returned codes before choosing a code for create_cost_centre — a code must be unique among live centres. Tell the user what the existing structure means before suggesting a change.

List ungrouped accounts with DETERMINISTIC grouping suggestions (curated rules + name/group-path matching — no AI is involved; Datavrn never applies a suggestion itself). Paginated. Each row carries a reason and a confidence tier: present them to your user GROUPED BY CONFIDENCE, and call out low-confidence and balance-bearing rows for individual attention — a single blanket approval is not a review of the low-confidence tail. Confirm only what your user approves via confirm_groupings. Returns a summary (counts by confidence tier) plus one page of suggestion rows — fetch tier by tier with the confidence filter instead of everything at once; pass include='confirmed' to see already-confirmed groupings.

List the reporting periods a Schedule III statement can be prepared for (periods with a live Trial Balance). Returns period ids for get_schedule3_workspace, save_py_values, and generate_schedule_iii.

List the profit centres for an entity. Use this to explain available targets before a user confirms any explicit mapping. This is status-only: it returns names and hierarchy, never rupee amounts.

List what a connected data source’s AUTOMATIC syncs have REPLACED for one entity — each one showing what was overwritten, how many records, and whether it can still be undone. Call this when a user says figures for a past period look wrong or changed on their own, and after any surprise in a period a connector covers. Datavrn keeps the replaced data for 30 days from the moment it was replaced: within that window state is "restorable" and preview_replacement_restore/restore_replacement can put it back; after it, state is "lapsed" — the record of what happened is kept and is still listed here, but it can no longer be undone from this connection, so tell the user to contact Datavrn support if they need that data recovered. "restored" means it has already been put back. Only syncs that ran UNATTENDED are listed: a replacement someone on the team previewed and confirmed themselves is not offered for undo, by design. window_closes_at is the date the undo window shuts. If connection_attributed is false, Datavrn can no longer prove which connection made that replacement — say so rather than naming this one. To find these without a connection id, call get_pending_work: it lists every still-undoable replacement across the entities you can see, with the entity and connection to use here.

Review reporting-line classification status and deterministic suggestions for an entity and reporting period. This is status-only: it returns names, line labels, confidence, reasons, and balance-bearing booleans, but never debit, credit, balance, or any rupee amount. Present suggestions grouped by confidence tier and target, with exact counts and both unmapped_total and unmapped_with_balance; do not call either count pending.

List the frozen Schedule III workbook versions for an entity (newest first), including each version’s period, template, and unclassified count at build time.

List every Significant Accounting Policy and Other Regulatory Information affirmation for this statement, with the text that will print, whether a template choice is still unresolved, and what was answered LAST YEAR. This is what makes two rules actionable rather than decorative: never resolve a bracketed choice for your user, and always tell them when an answer differs from last year. CHECK THE ROW’S captured FLAG BEFORE YOU CALL ANYTHING A POLICY CHANGE. differs_from_prior is true in two different situations and only one of them is a change: with captured true the wording was set this year and genuinely differs, which IS a change in accounting policy requiring disclosure under AS-5 / Ind AS 8; with captured false nothing has changed — last year was answered, this year has not been, and the text shown is Datavrn’s generic template wording, which is what will PRINT unless last year’s wording is entered again. Warn your user about that second case explicitly: it silently replaces a policy they wrote. The summary gives you both numbers separately — changed_total (real AS-5 changes) and not_carried_forward_total (answered last year, not yet this year); differs_from_prior_total is simply the two added together. An unresolved choice blocks finalisation, so work through them with your user before generating the version you intend to finalise. "Last year" means the SAME MONTH ONE YEAR EARLIER — the same comparative period the statement itself reports — not the period immediately before this one. The summary names it: prior_period_label is the year that was compared against, and prior_period_found tells you whether Datavrn holds that year at all. A blank last-year answer means nothing was recorded for that year — when prior_period_found is false it means Datavrn has no such reporting period, so there is nothing to compare. Either way it does NOT mean last year matched this year; say which of the two it is.

Show ONE upload’s figures as they stand right now, and get the approval confirm_complete_chart needs. Call this after list_chart_rebaselines, for the one upload your user is considering. It reports the same counts the list does — how many distinctive ledger names Datavrn already treats as evidence (trusted_considered), how many this upload adds (incoming_considered), how many are on both sides (matched), the two coverage ratios, and which direction fell short (shortfall) — re-read at this moment rather than when you listed. Read them to your user in their own terms and ask them plainly whether that upload is the entity’s whole book now. NEVER decide this from the numbers yourself — a large jump, a round number or a long gap is a reason to ASK, never a reason to conclude. Only the person who knows the client’s books can answer it. The approval is single-use, expires in 15 minutes, and is tied to this entity, this upload, the member you name, and the exact figures returned here. If the entity’s uploads change in between — including a later clean file that resolves this on its own — the approval is spent and you start again from this call. Datavrn refuses and changes nothing if this upload is not awaiting a complete-chart confirmation: it was never held out of the evidence, someone already confirmed it, or it is one Datavrn asked about directly — for that last one, answering that question is what settles it.