# Home
Welcome to Tally's Technical Documentation Repository
Tally is an intelligent billing platform built for enterprise logistics, that connects your operations, finance, and commercial systems into a single, automated workflow. Tally is designed to supercharge your team, spending less time chasing paperwork and invoices and more winning business.
#### What Tally Does
Tally sits at the center of your finance and operations stack, integrating with the tools you already use: **Gmail/Outlook, TMS/WMS, ERP/Accounting,** and your **bank accounts** — to automate the full invoice lifecycle from creation to collections.
Here's what that looks like end to end:
* **Invoice Creation:** Tally prepares invoices ready to send, complete with backup documents, applied contract rates, and quotes.
* **Invoice Audit:** Customer invoices (AR) and Carrier invoices (AP) are automatically reviewed and audited before anything moves forward.
* **Invoice Submission:** Invoices are delivered to your customers in any format they require: PDF, Excel, or direct portal upload.
* **Collections:** Cash application runs automatically, with aging reports, dunning, and remittance handled for you.
# How Tally works
Financial operations teams manage billing across a huge variety of shipments, clients, and service types — each with their own contracts, rate structures, and documentation requirements. Generating accurate invoices at scale, and getting them out the door quickly, is one of the most operationally demanding parts of the business.
Tally ingests your unstructured commercial and operational data — contracts, rate cards, quotes, SOPs, emails, TMS and WMS feeds — and uses it to generate the perfect invoice. It helps finance teams accelerate and automate the most painful parts of the job: hunting for backup documents, checking for completeness, generating line items, submitting invoices, tracking aging, and managing cash application and remittance.
#### **How it works**
The engine behind Tally is the Logistics Context Graph (LCG) — a living knowledge graph that models your freight operation as a connected network of shipments, carriers, invoices, contacts, and rates.
The LCG resolves fragmented data automatically. It recognizes that "Ref #123" on an invoice and "Container 123" in an email thread refer to the same shipment — and links them without manual mapping, regardless of how your carriers or partners format their data.
#### What You Can Build
The LCG is designed as an intelligence layer for your applications:
* Agentic assistants: Natural language Q\&A over your entire logistics operation
* Operational/Financial dashboards: Real-time financial insights on a shipment level across all data sources
* Exception management: Detect anomalies by traversing relationships (e.g., a shipment missing expected events)
* Cost analytics: Aggregate charges across shipments, lanes, carriers, and time periods
* Compliance & audit: Full provenance trail from any data point back to its source document
* Workflow automation: Trigger actions based on graph state changes (new shipment, milestone reached, charge discrepancy)
[Learn more about our Logistic Context Graph](/context-graph-overview/introduction)
# SSO
### Single sign-on (SSO)
Tally supports SSO so your team can sign in with your existing identity provider — no separate Tally password required.
Once SSO is active, users enter their work email on the login page and are redirected to your IdP (Microsoft Entra ID, Okta, Google Workspace, and others). Password login is disabled for your organization once SSO is configured.
#### Setting up SSO
SSO setup is self-serve. A Tally admin can configure it directly from the product:
1. Sign in to Tally as an admin
2. Go to Settings → Company → Authentication (`/settings/company/authentication`)
3. Click Configure SSO
4. Open the SSO Configuration Portal link (valid for 5 minutes)
5. In the portal, connect your identity provider and complete the SAML setup
6. Assign the users or groups who should have access
When setup is complete, the Authentication page shows SSO is configured. Users with access through your IdP can sign in immediately.
> Note: You need to be logged into Tally to generate the portal link. If your IT team doesn't have a Tally account yet, invite them from Settings → Company → Users first, or have an existing admin generate the link and share it.
#### What users see at login
After SSO is live, the login flow is automatic:
1. User enters their work email address
2. Tally detects SSO for their organization
3. User is redirected to your identity provider to sign in
4. After successful authentication, they land in Tally
No password field is shown for SSO-enabled organizations.
# How Tally connects to your emails
Tally connects to Microsoft 365 to read and act on the emails your team handles — monitoring inboxes, drafting replies, and sending on behalf of connected users.
There are two integration models. Both use Microsoft Entra ID and Microsoft Graph. The difference is who owns the app and how mailbox access is scoped.
#### Connect your organization to the Tally 365 app
Best for: Teams that want the fastest setup with minimal IT work.
Tally provides a shared Microsoft 365 app. Your IT admin grants admin consent once, installing Tally into your Entra tenant.
After consent, an admin configures which mailboxes Tally monitors from Settings → Company → Email — picking individual users, distribution groups, or shared mailboxes directly in Tally.
Individual users can also connect their own mailbox from Settings → Profile (`/settings/profile`) for delegated access (e.g. sending as themselves). That step is per-user and uses OAuth sign-in.
How access works: Admin consent unlocks org-wide monitoring. Users you select in Company Email settings are monitored via Tally's app. Profile connections are optional and user-driven.
{% content-ref url="/pages/JpP5s6kfyyIZgVZcEzQQ" %}
[Connect your organization to the Tally 365 app](/connect-your-systems/how-tally-connects-to-your-emails/connect-your-organization-to-the-tally-365-app)
{% endcontent-ref %}
***
#### Connect via your organization's own MS Entra app
Best for: Organizations with strict security requirements who want full control over the integration app and precise, group-based access scoping.
Your organization creates and owns the Microsoft Entra app registration. You provide Tally with credentials for that app, and you control permissions, conditional access, and revocation entirely within your tenant.
The key difference is how mailboxes are scoped. As part of setup, your admin:
1. Creates a mail-enabled security group (e.g. `TallyMonitored`) containing only the mailboxes Tally should access
2. Configures Exchange RBAC for Applications so Tally's app can only reach members of that group
3. Registers the group in Tally at the end of the setup wizard
Tally then connects to those mailboxes using app-only authentication — no individual user needs to sign in at Profile for monitoring to work. Adding or removing a mailbox is done by updating group membership in Microsoft 365.
How access works: Mailbox access is defined by security group membership + Exchange RBAC, not by per-user OAuth. Profile connections may still be used in some cases (e.g. shared mailbox sends), but the primary model is org-level, group-scoped app access.
{% content-ref url="/pages/9wMhNTvPn6rOz6kwj5jV" %}
[Connect via your organization's own MS Entra app](/connect-your-systems/how-tally-connects-to-your-emails/connect-via-your-organizations-own-ms-entra-app)
{% endcontent-ref %}
# Connect your organization to the Tally 365 app
IT Admin instructions for connecting Microsoft 365 emails
### Steps to connect your Outlook with Tally
1. Click connect with Microsoft below (needs to be done by an IT Administrator)
1. One-Click Installation: [Connect to Microsoft](https://login.microsoftonline.com/common/adminconsent?client_id=741c8ca7-a19f-4739-8d54-5cdc6ee3162a\&redirect_uri=https://app.tallygo.ai)
2. Access One-click Installation through Tally: User Profile (bottom left) > Settings > Email
3. IT Administrator login in to their account
4. Approve the Tally 365 app
5. Once redirected back to Tally your connection is successful.
6. From here, individual users can login to Tally to setup their mailbox access via User Profile (bottom left) > Settings > Profile > Connect Outlook
7. They will be redirected to outlook, where they can select their mailbox (may ask you to re-enter password)
8. They will then be redirected back to Tally and shown the connected email
# Connect via your organization's own MS Entra app
IT Admin instructions for connecting Microsoft 365 emails
Use this setup when your team wants its own Microsoft Entra ID app registration. This gives your security team direct control over consent, mailbox scope, and revocation. If you are fine using Tally's shared multi-tenant app, use [Connect Emails](/connect-your-systems/how-tally-connects-to-your-emails/connect-your-organization-to-the-tally-365-app).
Before you start:
* A logged-in Tally user must open **Settings → Email** and start the setup.
* You can generate a secure setup link for your IT or Microsoft admin. They do not need a Tally account.
* The setup link expires 3 days after creation.
* Certificate creation and upload are required for this flow.
### Steps to connect your custom Microsoft app to Tally
1. Start the setup in Tally
1. Go to **Settings → Email**.
2. Open **Custom Microsoft app registration**.
3. Click **Set up custom app**.
4. If your IT or Microsoft admin does not have a Tally account, generate the secure setup link and send it to them.
5. Copy the link when it appears. It is shown once and expires 3 days after creation.
Once in the setup wizard, follow the guide below to configure your app and Tally's access.
2. Create the app registration
1. Create the Microsoft Entra ID app registration that Tally will use.
3. Grant API permissions
1. Grant only the permissions required by the integration.
4. Scope mailbox access with RBAC
1. Grant Tally read access only to the mailboxes you want it to monitor by using Exchange Online RBAC for Applications.
5. Provide credentials to Tally
6. Create your certificate, upload it, then validate
1. Create a certificate in your app registration.
2. Upload the certificate to Tally.
3. Run validation to confirm the setup works.
Once validation succeeds, you should see this:
Once connected, select the mailbox you want Tally to monitor. Tally only has access to the mailboxes you configure.
# Introduction
Intro to Tally's Logistics Context Graph
Logistics operations are fragmented by nature. A single shipment touches dozens of emails, multiple documents, and several systems — each using different reference numbers and inconsistent naming conventions. No single source can maintain a complete operational picture.
Traditional databases try to force this reality into rigid schemas, requiring normalized keys and relationships that simply don't exist consistently across supply chain partners. The result is brittle join logic that breaks with every schema migration.
Tally takes a different approach. The Logistics Context Graph (LCG) is a labeled property graph that continuously ingests fragmented inputs — emails, PDFs, structured feeds — and resolves them into a richly connected knowledge graph across your entire operation. Relationships are first-class elements, not derived join artifacts. Entity resolution automatically recognizes that "Ref #123" on an invoice and "Container 123" in an email thread are the same entity, merging records across sources without a shared key.
The result is multi-hop traversal across your operational network — without the overhead of maintaining relational schemas as your data evolves. And ultimately, a foundation for agentic applications that reason about your operations the way your best operators do.
*Let's start with the end result — a resolved Shipment in the graph — then break down what makes it possible.*
The system is built on four stages:
| Stage | What It Does | You Get |
| ------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Connect | Integrate your structured and unstructured data sources | A single pane of continuous data flow into the graph |
| Extract | Tally extracts natural language, documents and other unstructured data into structured entities with metadata classifications | Clean, typed, normalized data entities with specific mapping to logistics context |
| Resolve | Extracted entities are linked and clustered into shipment-centric subgraphs | Complete operational context of shipments, customers, financials, and exceptions. |
| Query | Power your applications with graph intelligence and multi-hop reasoning | APIs and context to enable high fidelity agentic capabilities. |
# Connect: Integrating Your Data Sources
The graph's value is proportional to the data flowing into it. The LCG supports multiple data source types, with email and operating systems being the most common starting point, most logistics context lives in inboxes while operational steps live in operating systems.
#### Document and System Feeds
Documents can be ingested directly via PDFs, spreadsheets, and images from your WMS, TMS, or other systems. Every source passes through the same pipeline, making integration source-agnostic.
#### Email Connectors
The system provides native connectors for Gmail and Outlook / Microsoft 365, including shared mailbox support. Once connected via OAuth, the system continuously syncs new messages using incremental cursors. Users connect once, and the graph stays current automatically.
#### Full Provenance
Every entity in the graph traces back to its origin. When an agent answers "what are the charges on this shipment?", it can also tell you which document and which email thread those charges came from.
# Extract: Turning Unstructured Data into Structured Entities
Raw emails and documents are unstructured, free-form text, with inconsistent formats, and implicit relationships. The extraction layer transforms this content into typed, structured entities that the graph can reason on.
Our proprietary AI extraction engine classifies content for relevance, parses text from attachments and performs structured extraction into validated entity schemas. Every extracted entity is schema-validated before entering the graph, ensuring no untyped or malformed data gets through.
#### What Gets Extracted
Extraction is source-agnostic. Whether an HBL number appears in a subject line, an email body, or a scanned PDF, it enters the graph as the same entity type. The same identifier appearing across multiple sources strengthens the graph rather than creating duplicates.
Every piece of content can produce a rich set of logistics entities:
Identifiers: The reference numbers that tie logistics operations together. These are the most critical extraction, as they're how shipments are tracked across systems. For example, below are of the identifiers we look at
| Type | Example | Purpose |
| --------------------- | ------------- | ----------------------------- |
| House Bill of Lading | TPEB1234567 | Primary shipment reference |
| Booking Number | BKG-2024-0892 | Carrier booking reference |
| Master Bill of Lading | MAEU123456789 | Consolidation-level reference |
| Purchase Order | PO-44210 | Commercial reference |
| Invoice Number | INV-2024-3391 | Financial reference |
| Container Number | MRKU4512870 | Physical unit tracking |
Identifiers also carry relationships to each other — an invoice may reference a booking, a master bill may contain multiple house bills:
**Parties & Contacts:** Organizations (shipper, consignee, carrier, forwarder, customs broker) and the people within them, with their specific roles on each shipment.
**Route & Cargo:** Multi-modal route legs (ocean, truck, rail, air) with origin/destination locations, vessel/flight info, and ETD/ETA timestamps. Containers with type and seal info. Commodities with HS codes, weight, and dimensions.
**Financial:** Charges with amount, currency, and billed-by/billed-to parties. Rate cards and quotations linking pricing to service providers.
**Events:** Milestone events (booking confirmed, cargo received, vessel departed, customs cleared, delivered) with timestamps and status tracking (estimated, planned, actual).
# Resolve: Building Shipment-Centric Subgraphs
Extraction produces structured entities, but they're still disconnected fragments. The resolution layer links them together into coherent, shipment-centric subgraphs, complete operational pictures assembled automatically from fragmented communications.
#### How Resolution Works
The core challenge: given a set of identifiers extracted from a new email or document, determine which Shipment they belong to or whether a new Shipment should be created.
Our proprietary matching algorithm distinguishes between identifiers that define a shipment (like a House Bill of Lading) and identifiers that merely reference one (like an invoice number). This ensures high-precision matching while still capturing the full context around each shipment.
#### Multi-Shipment Detection
A single email often contains information about multiple shipments. The system detects these multi-order scenarios automatically and resolves each order group independently:
#### The Resolved Shipment
A single Shipment in the graph may aggregate context from 30+ emails, 15+ documents, and dozens of entities, all assembled automatically through intelligent matching. This is what makes Tally’s LCG architecture dramatically more valuable than a document store or flat database.
Once resolved, every extracted entity is linked to its shipment, building a complete operational picture:
Tally handles duplicate detection and merging (automatically combining shipment fragments that turn out to be the same movement) and party resolution (recognizing that "Maersk Line", "Maersk A/S", and "MAEU" refer to the same organization).
# Query: Powering Tally’s Agentic Applications
The final layer of the Tally architecture enables applications to query and reason over the connected dataset. Tally’s LCG serves as the semantic intelligence layer for all downstream workflows.
To query this network, we utilize Graph RAG, which bypasses the limitations of standard vector embeddings or BM25 keyword search. Rather than retrieving isolated documents based on text similarity, our querying agent performs deterministic graph traversal. It follows explicit edges, hopping from a Party node to a Shipment node, assessing Charge nodes, and validating against Document nodes. This multi-hop traversal allows the system to synthesize precise answers to complex supply chain queries that would break traditional search architectures.
#### Graph RAG: Natural Language Queries
Graph RAG, is a retrieval architecture where an AI agent dynamically generates and executes Cypher queries against the LCG in response to natural language inputs. Rather than retrieving documents by text similarity, the agent traverses explicit graph edges — following relationships from a Shipment node through its Charge nodes, validating against source Document nodes — to synthesize precise, provenance-backed answers. Because the agent introspects the schema at query time, it adapts to new entity types and relationships without retraining.
#### The agent is equipped with tools to:
| Tool | Purpose |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| Schema discovery | Understand the graph's current shape — entity types, relationships, and properties — so queries are always accurate |
| Graph query | Execute structured queries with automatic tenant scoping and safety validation |
| Identifier search | Fuzzy search across all reference numbers (tracking numbers, BOLs, POs) |
| Party search | Fuzzy search across company names to resolve informal references |
The schema is introspected dynamically, so as your data evolves, the agent's understanding evolves with it.
#### REST API
The system exposes a structured API for direct access, some examples:
| Endpoint | What You Get |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| GET /graph/shipments | Paginated shipment list with filters like status, mode, date range, origin, destination, carrier, and customer |
| GET /graph/shipments/:shipmentId | Complete shipment detail: identifiers, parties, route legs, cargo, charges, milestones, related documents, and linked communications |
| GET /graph/shipments/:shipmentId/timeline | Shipment timeline combining estimated, planned, and actual milestone events |
| GET /graph/shipments/:shipmentId/evidence | Provenance graph showing where each fact came from: email, attachment, document, or upstream system record |
Each endpoint exposes the following search parameters:
| Search Parameter | Purpose |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| q | Free-text query such as a bill of lading number, company name, container number, invoice number, or phrase from an email |
| types | Restrict search to entity classes like shipment, identifier, party, document, or email |
| filters | Narrow results by tenant-safe dimensions such as date range, shipment mode, customer, carrier, status, or source system |
| limit / cursor | Paginate results for UI workflows and agent tooling |
| includeEvidence=true | Return snippets, matched fields, and provenance so users can see why a result matched |
# Graph entities
| Entity | Description |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| Shipment | Central entity representing a freight movement. All other entities connect to it. |
| Identifier | A reference number (HBL, booking, PO, invoice, container, etc.) that links to a shipment. |
| Party | An organization — carrier, forwarder, shipper, consignee, customs broker — with a specific role. |
| Contact | An individual person associated with a party. |
| Leg | A route segment (ocean, truck, rail, air) with origin, destination, and schedule. |
| Container | A physical shipping container with number, type, and seal. |
| Commodity | Goods being shipped, with HS codes, weight, and dimensions. |
| Charge | A financial line item with amount, currency, and billed-by/billed-to parties. |
| Event | A milestone (booked, departed, arrived, cleared, delivered) with timestamp and status. |
| Location | A port, airport, city, or facility with UN/LOCODE. |
| Email / Document | Source records that maintain full provenance for every entity in the graph. |