Truto vs Rutter: 2026 Buyer Decision Guide & Architecture Checklist

If you are evaluating unified API vendors for your engineering team in 2026, the decision usually comes down to one fundamental architectural question: do you need a fintech-specialist API or a general-purpose integration engine? The search intent behind comparing Truto and Rutter usually stems from a painful engineering reality. Your team is drowning in NetSuite SOAP quirks, QuickBooks pagination logic, and fragmented REST APIs. You need infrastructure to abstract the mess so your developers can actually focus on your core product.

The short version of this comparison comes down to architectural alignment with your product's core use case. Rutter is a specialized, sync-and-cache unified API built specifically for B2B fintech workflows. Rutter APIs allow you to read, update, write, and remove data across 60+ accounting, commerce, payments, and ads platforms used globally by your customers. Truto is a general-purpose, zero-code unified API engine spanning 27+ software categories with a real-time pass-through architecture designed for broad B2B SaaS interoperability and strict compliance.

Engineering leaders cannot afford to guess which architectural pattern fits their needs. Choosing a caching engine when you need real-time data - or choosing a specialized fintech API when your roadmap requires CRM and HRIS integrations - results in expensive migrations a year down the line. If your roadmap stays strictly inside fintech reads, Rutter is an excellent choice. If it extends to CRM, HRIS, ATS, ticketing, or strict zero-data-retention compliance, Truto's architecture maps better.

This guide breaks down the technical differences between these two platforms, examining their data freshness guarantees, custom field handling, and rate limit normalization. We will provide a definitive checklist to help you justify your build-versus-buy or vendor selection decision.

The Enterprise Integration Dilemma

Before analyzing the specific architectures of Truto and Rutter, we must establish why B2B SaaS teams are aggressively adopting unified APIs in the first place. The sheer volume of SaaS applications in the enterprise makes point-to-point integrations mathematically unsustainable. Integration coverage is no longer just a feature - it is a gating purchase criterion.

The average enterprise manages 291 SaaS applications in 2026, up from 254 in 2023 and 110 in 2020. Large enterprises with over 10,000 employees currently use an average of 473 different applications, most of which are cloud solutions. This widespread adoption creates opportunities for B2B lead generation across virtually every business vertical.

Missing the specific integration your prospect needs directly impacts your sales pipeline. When your prospect's IT stack looks like that, a single missing connector kills the deal. You have a roadmap commitment - an ATS sync for HR Tech, a NetSuite integration for spend management, a multi-platform ticketing pipeline - and a fixed engineering budget. Building and maintaining 30 connectors in-house drains senior engineering resources. Rutter and Truto both reduce that cost, but they reduce different parts of it based on their architecture.

A quick comparison before going deeper:

For a fuller architectural deep dive across the wider ecosystem, see our 2026 Unified API Architecture Comparison.

Unified Accounting API vs Building Custom Integrations

Before comparing vendors, many teams first ask whether they should build accounting integrations in-house. For a single QuickBooks connector, this looks tractable. For a portfolio - QuickBooks, Xero, NetSuite, Sage Intacct, Zoho Books - the math changes quickly.

The custom integrations accounting API challenges most teams underestimate:

• Auth complexity per provider. QuickBooks uses OAuth 2.0 with realm IDs. NetSuite requires OAuth 1.0 Token-Based Authentication with HMAC-SHA256 signature generation on every single request. Xero uses OAuth 2.0 with tenant IDs. Sage Intacct uses SOAP with session tokens. Each is a separate credential lifecycle to build, monitor, and refresh proactively.
• Multiple API surfaces per provider. NetSuite alone requires orchestrating across three distinct surfaces: SuiteTalk REST for record CRUD, SuiteQL (a SQL-like query language) for reads with JOINs, a deployed SuiteScript Suitelet for PDF generation and dynamic field metadata, and legacy SOAP for tax rate details that SuiteQL does not expose. A single "list purchase orders" operation JOINs transaction, entity, vendor, transactionline, and subsidiary tables.
• Feature-adaptive query construction. A NetSuite account can be single-currency + single-subsidiary, multi-currency only, OneWorld only, or both. That is four query variants per resource, detected at connection time by probing the currency and subsidiary tables. Custom integrations must implement this detection or ship broken queries to a portion of customers.
• Schema drift and custom fields. Every enterprise NetSuite instance has custom body fields (custbody*), custom column fields (custcol*), custom forms, and custom segments. Reading them requires runtime record introspection, not static generated types.
• Polymorphic resource semantics. NetSuite stores vendors and customers as separate record types, but from an accounting perspective they are both "contacts". Similarly, classes, departments, and locations are all forms of tracking category. Your custom integration has to build these abstractions provider by provider or leak vendor-specific concepts into your product surface.
• Long-tail maintenance. Providers deprecate endpoints, rotate rate limit windows, add required fields, and change error shapes. One senior engineer can absorb one integration's maintenance load. Ten integrations require a dedicated team.

A unified accounting API absorbs all of the above into one contract. GET /unified/accounting/invoices?integrated_account_id=... returns the same normalized shape whether the underlying provider is QuickBooks, Xero, or NetSuite. The trade-off is that you inherit the vendor's opinions on the unified schema, which is why the vendor's flexibility on custom fields and per-tenant overrides (covered in the next section) is the deciding factor for enterprise deployments.

If your product only ever needs QuickBooks and you have exact control over which QuickBooks fields matter, building custom is defensible. If you need three or more accounting providers, or one provider with heterogeneous enterprise instances, a unified API pays for itself within the first two integrations.

Architectural Philosophy: Fintech Specialist vs General-Purpose Engine

The most glaring difference between Truto and Rutter is horizontal coverage versus vertical specialization.

Rutter optimized for one job and did it exceptionally well. Rutter is the data infrastructure that powers many of the next generation ecommerce tools, from challenger banks and credit cards to dropshipping and fulfillment companies to accounting and marketing platforms. Their schemas, webhooks, and authentication flows are tuned for fintech use cases - underwriting on Shopify and Amazon sales history, syncing QuickBooks ledgers for lending decisions, or pulling ad spend for ROAS-based credit models. If you are building a corporate credit card or a revenue-based financing tool, Rutter's category selection aligns well with your needs—similar to the specialized financial focus we analyzed in our Truto vs Codat comparison.

However, if you are building a general B2B SaaS product - such as a customer success platform, an AI agent, or a security compliance tool - your integration needs will inevitably span across multiple departments. You will need to pull employee data from an HRIS (Workday, Gusto), read ticket statuses from an ITSM (ServiceNow, Jira), and update deal stages in a CRM (Salesforce, HubSpot).

Truto took a different path to handle this broad horizontal reality. It provides coverage across 27+ software categories. Even within the financial domain, Truto offers a deep commerce and accounting unified API that handles the exact same QuickBooks, Xero, and NetSuite integrations as Rutter, but does so on a highly extensible foundation.

Instead of designing for one vertical, Truto is a generic execution engine that runs declarative configurations. This unique architectural pattern relies on zero integration-specific code.

In legacy integration platforms, adding a new provider requires writing custom scripts or maintaining branching logic in the runtime. Truto's runtime takes a declarative JSON manifest describing how to talk to a third-party API, and a declarative mapping describing how to translate between unified and native formats. It then executes both without any awareness of which specific integration it is running.

flowchart LR
    A[Customer API Request] --> B{Unified API Layer}
    B --> C[JSONata Mapping Engine]
    C --> D[Provider Config Manifest]
    D --> E[Proxy / HTTP Client]
    E --> F[Live Third-Party API]
    F --> E
    E --> G[Response Normalizer<br>JSONata]
    G --> A

The practical effect: if you ask Rutter for a Linear ticket schema or a Workday HRIS sync, the answer is no - those are out of scope. If you ask Truto for a deeper Shopify product feed than what comes out of the box, you can ship a custom resource via configuration without waiting on a vendor roadmap. The trade-off is honest: Rutter has more pre-baked domain semantics in its accounting models because that is where its engineering hours went. Truto emphasizes massive category coverage and flexibility over rigid opinionation.

Data Freshness: Sync-and-Cache vs Real-Time Pass-Through

The fundamental technical divergence between Rutter and Truto lies in how they handle data storage and retrieval. This single architectural decision dictates your product's data freshness, security posture, and compliance overhead.

Definition: A sync-and-cache unified API stores a normalized copy of customer data and serves reads from that cache. A pass-through unified API proxies each read live to the upstream provider and returns the response without retaining the payload.

Rutter's Sync-and-Cache Architecture

Rutter utilizes a sync-and-cache model. Rutter's own documentation describes the model precisely. Rutter does an "initial sync" of a user's data when they authenticate your app. This may take hours to days depending on the size of the data. Once this process completes, Rutter automatically updates data from the platform on a regular cadence. Each time an Incremental Sync runs, our system automatically computes any data changes and fires webhooks accordingly.

This architecture is highly optimized for batch analytics and underwriting. If a lending algorithm needs to analyze three years of Shopify transaction history to approve a loan, querying a normalized cache is faster than paginating through live APIs. Industry-published numbers put cached queries in the 100-300ms latency range.

However, caching introduces liabilities for general B2B SaaS, and Rutter is upfront about the limitations of relying on webhooks for real-time updates: Webhooks are not 100% reliable. Expect a small percentage of webhooks to get dropped under normal working conditions. Make sure to handle these missing webhooks gracefully, so that the application still syncs even if no webhooks are received. We recommend calling the API endpoints regularly to check for updates in addition to using webhooks for real-time updates.

Truto's Real-Time Pass-Through Architecture

Truto inverts the model. It utilizes a real-time proxy API architecture that ensures zero data retention and zero staleness.

When your application requests data via Truto, the platform does not query a local database. A GET /crm/contacts call is translated by a JSONata mapping into the native HubSpot or Salesforce request, executed against the live API, and the response is normalized on the way back. Nothing is persisted in Truto.

sequenceDiagram
    participant SaaS as Your Application
    participant Truto as Truto Proxy Engine
    participant Upstream as "Third-Party API (Salesforce)"
    
    SaaS->>Truto: GET /unified/crm/contacts<br>(Standardized Request)
    Note over Truto: Injects OAuth Token<br>Translates to SOQL
    Truto->>Upstream: GET /services/data/v60.0/query/?q=...
    Upstream-->>Truto: Raw JSON Response<br>(Native Format)
    Note over Truto: Executes JSONata<br>Normalizes Schema
    Truto-->>SaaS: Standardized JSON Response<br>(Zero Data Stored)

This pass-through model matters in three critical scenarios:

1. Strict zero-data-retention compliance: Replicating your customers' sensitive financial, HR, or CRM data into a third-party vendor's database drastically expands your threat surface. Enterprise security reviews, HIPAA, EU residency, and DORA evaluations get materially easier when the vendor never stores customer records. See our zero data retention guide for the operational detail.
2. Operational workflows: A 60-minute polling delay is fatal for operational SaaS. If a sales rep updates a deal to "Closed Won" in Salesforce, or a user clicks "create invoice", your system needs to know immediately, not an hour later.
3. AI agents: When an agent reasons over CRM context, stale data produces hallucinated outputs. Pass-through reads keep the agent grounded in live reality.

The honest counterweight: pass-through has a latency cost. Passthrough request latency generally falls in the 800ms - 1.2s range depending on the upstream provider. For background syncs, this is irrelevant. For a user-facing button, it is a UX consideration you should test in your own product. For a deeper exploration, read Tradeoffs Between Real-time and Cached Unified APIs.

Handling Custom Fields and Per-Tenant Overrides

One of the hardest problems in SaaS integrations is managing schema drift and custom objects. No two enterprise instances of Salesforce, Jira, or NetSuite are identical. Customers heavily modify their systems of record, adding custom fields that your application needs to read or write.

Rutter exposes custom fields through its standardized schema with a custom_fields or passthrough_fields pattern, depending on the resource. This works for read-heavy workflows but starts to break down when you need to deeply remap data shapes for a single enterprise tenant without forking your application code.

Truto solves this through a declarative mapping layer powered by JSONata. Because Truto relies on configuration rather than hardcoded logic, it exposes a powerful 3-level override hierarchy that allows you to handle custom fields without writing custom code.

The 3-Level Override Hierarchy

The generic execution engine reads mappings from, in order of precedence:

1. Platform Unified Model (Level 1): The baseline JSONata manifest shipped with the connector. This handles standard fields like first_name, email, and company_name across all supported providers.
2. Environment Override (Level 2): Your application might require specific data that is not part of the standard unified model. You can inject a JSONata expression at the environment level to extract a specific native field across all your customers.
3. Linked Account Override (Level 3): The ultimate escape hatch. If a single enterprise customer has a unique custom field (e.g., x_custom_billing_tier_c in Salesforce), you can apply a per-tenant JSONata override specifically for that tenant's linked account.

A simplified override for a per-customer custom field on Salesforce contacts looks like this:

{
  "unified_field": "annual_revenue_bucket",
  "jsonata": "$lookup($.Custom_Revenue_Tier__c, $.RevenueBucketMap)",
  "scope": "integrated_account",
  "account_id": "acct_9f3..."
}

The engine resolves this override at request time. No code deploy. No fork of the integration. The same Salesforce connector serves a customer with stock fields and a customer with 47 custom fields, with different mappings, in the same pool. This architecture ensures that the unified API bends to fit your customers' reality, rather than forcing your customers to conform to a rigid API schema.

Rate Limits, Pagination, and Error Handling

When building integrations, the happy path is easy. The true engineering cost lies in handling the myriad ways third-party APIs fail. Upstream APIs have wildly different rate limit conventions. QuickBooks has per-realm limits. Salesforce has org-level daily caps. Shopify has bucket-based throttling. HubSpot has burst windows. Any unified API has to take a position on how to expose these to your code.

The Reality of Rate Limits

Rutter abstracts this away. Rutter abstracts the different ways to sync data by handling rate limiting and pagination under the hood and delivering cached data normalized to our API. This provides the developer with a single way to access real-time data without having to worry about different fetching rules. This works because reads come from their cache, not the live provider - the rate limit is on Rutter's sync workers, not your app.

Truto takes the opposite, more transparent stance. When an upstream API returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller. Truto does not magically absorb, retry, or apply backoff on your behalf. You own the retry logic.

This is a deliberate architectural decision. Masking rate limits behind opaque retry queues leads to system deadlocks and unpredictable latency. Senior engineers require deterministic behavior to manage their own job queues and circuit breakers.

Instead of hiding the failure, Truto normalizes the metadata. Every provider returns rate limit information differently. Truto inspects the upstream response and normalizes this data into standardized HTTP headers per the IETF specification:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

This normalization allows your backend to implement a single, unified exponential backoff strategy across hundreds of different SaaS APIs. A minimal client-side retry pattern looks like this:

async function callTrutoWithRetry(url: string, opts: RequestInit, max = 5) {
  for (let attempt = 0; attempt < max; attempt++) {
    const res = await fetch(url, opts);
    if (res.status !== 429) return res;
    const reset = Number(res.headers.get('ratelimit-reset') ?? '1');
    const jitter = Math.random() * 250;
    await new Promise(r => setTimeout(r, reset * 1000 + jitter));
  }
  throw new Error('Rate limit retries exhausted');
}

Pagination Normalization

Pagination is another massive source of technical debt. Provider A uses cursor-based pagination. Provider B uses offset/limit. Provider C uses page numbers.

Both platforms abstract this completely, but Truto's approach is declarative. The proxy API exposes a standardized cursor-based pagination interface to your application. Each resource configuration defines how to extract next_cursor from the response, dynamically translating it into the specific pagination mechanism required by the upstream provider. You write one pagination loop in your codebase, and it works across 100+ integrations. See How Unified APIs Handle Pagination Differences for the full breakdown.

MCP Servers for AI Agents: Why Architecture Matters

The Model Context Protocol is reshaping how AI agents interact with enterprise SaaS. If you are evaluating the best MCP server platform for AI agents connecting to enterprise SaaS, the unified API architecture underneath is the factor that determines whether your agents get live data or stale cache reads - and whether your security team signs off on the deployment.

The scale of this shift is not theoretical. Gartner predicts that 40% of enterprise applications will integrate task-specific AI agents by the end of 2026, up from less than 5% in 2025. MCP adoption has tracked a parallel curve: the protocol went from Anthropic's launch in November 2024 to native support in OpenAI, Microsoft Copilot Studio, and AWS Bedrock, with combined SDK downloads reaching 97 million monthly by March 2026. For engineering teams building agent-powered products, the MCP server platform you choose directly shapes your agent's accuracy, security posture, and time-to-production.

How Truto Generates MCP Servers Dynamically

Truto turns any connected integration into an MCP-compatible tool server without hand-coding tool definitions for each provider. When a customer connects their Salesforce, HubSpot, Jira, or any other supported integration, Truto automatically generates MCP tools from that integration's resource definitions and documentation records.

The generation is documentation-driven. A tool only appears in the MCP server if it has a corresponding documentation entry - a quality gate that ensures only well-described endpoints are exposed to LLMs. Each MCP server is scoped to a single connected account, and the server URL contains a cryptographic token that encodes which account to use, which tools to expose, and optionally when the server expires. The URL alone is enough to authenticate and serve tools - no additional client configuration required.

This matters for AI agents because:

• Tool calls hit live APIs. MCP tool execution delegates to the same real-time proxy API described above. When an agent calls list_all_hub_spot_contacts, it gets the current state of the CRM, not a cached snapshot. Stale data in agent context leads to hallucinated outputs and incorrect actions.
• Method-level access control. You can restrict an MCP server to read-only operations (get, list), write-only (create, update, delete), or specific individual methods. A support agent that should only read tickets never gets a delete tool.
• Tag-based tool scoping. Integration resources can be grouped by functional area (e.g., ["crm", "support", "directory"]). An MCP server created with tags: ["support"] only exposes ticket and comment tools, not CRM deal tools. This keeps the agent's tool context focused and reduces prompt token waste.
• TTL servers for ephemeral access. MCP servers can be created with an expires_at timestamp. Useful for giving a contractor agent access for a week or generating short-lived servers for automated workflows. Expiration is enforced at the token storage layer - once expired, lookups fail immediately.

Where Rutter Stands on MCP

Rutter's architecture is not designed for real-time MCP tool serving. Their sync-and-cache model means any MCP tool built on top of Rutter reads from a normalized cache with the same 60-minute polling cadence discussed earlier. For agent workflows where an AI reasons over financial data that was synced an hour ago - like generating an underwriting summary - this is acceptable. For operational agent workflows where the agent needs to read a ticket status, update a CRM record, and confirm the write succeeded in the same turn, the caching layer introduces unacceptable staleness.

Rutter also does not expose a native MCP server endpoint. You would need to wrap their REST API in your own MCP server implementation - manageable but additional infrastructure to build and maintain.

Enterprise MCP Security Considerations

MCP security is not a peripheral concern. The OWASP MCP Top 10, published in late 2025, catalogs risks spanning tool poisoning, context spoofing, and token mismanagement. The NSA published MCP-specific security design guidance in May 2026. When your security team evaluates an MCP server platform, the underlying architecture directly determines the risk surface.

A zero-data-retention proxy architecture like Truto's means the MCP server never stores your customer's CRM records, employee data, or financial transactions. The agent gets live data, acts on it, and nothing persists in the platform. A sync-and-cache architecture means a copy of that data exists in the vendor's infrastructure - expanding your data processor obligations under GDPR, HIPAA, and DORA.

Truto's MCP servers also support a dual-auth mode: the token URL provides the primary authentication, and an optional require_api_token_auth flag adds a second layer requiring a valid API token in the Authorization header. This is useful when MCP server URLs might be visible in logs or configuration files but you need to ensure only authenticated team members can invoke tools.

The Buyer Decision Flow

Choosing between Truto and Rutter - or deciding whether you need both - requires aligning the vendor's architecture with your product's specific requirements. Rather than a static feature checklist, walk through these decision questions in order. Each answer narrows the field.

Step 1: What is your primary integration domain?

flowchart TD
    A["What categories do you<br>need to integrate?"] -->|Accounting, Commerce,<br>Payments, Ads only| B["Rutter is a strong fit"]
    A -->|CRM, HRIS, ATS,<br>Ticketing, or 3+ categories| C["Truto is a strong fit"]
    A -->|Fintech core +<br>CRM/HRIS for GTM| D["Consider running both"]
    B --> E["Step 2: Data freshness"]
    C --> E
    D --> E

Step 2: What data freshness does your core workflow require?

• Batch analytics / underwriting (hourly staleness acceptable) - Rutter's cached reads are optimized for this.
• Operational workflows / user-facing actions (sub-second freshness required) - Truto's pass-through proxy returns live data on every call.
• AI agent reasoning (agent must act on current state) - Pass-through architecture prevents hallucinated outputs from stale context.

Step 3: What is your compliance posture?

• Standard SOC 2 - Either platform works.
• Zero data retention required (HIPAA, EU residency, DORA, enterprise security reviews that prohibit third-party data storage) - Truto's proxy architecture never persists customer data.
• On-prem or region-restricted deployment - Truto supports these deployment models.

Step 4: Do you need MCP server support for AI agents?

• No agent workflows planned - Skip to Step 5.
• Read-only agent over cached financial data - Rutter's API can be wrapped in a custom MCP server.
• Read/write agent across multiple SaaS categories with method-level controls - Truto generates MCP servers dynamically with tag filtering, method restrictions, and TTL expiration.

Step 5: How customized are your customers' SaaS instances?

• Mostly stock configurations - Either platform's standard schema works.
• Heavy custom fields and objects (enterprise Salesforce, NetSuite, Workday) - Truto's 3-level JSONata override hierarchy handles per-tenant remapping without code deploys.

Enterprise Profile Mapping

If you prefer a shortcut, find your profile below:

For a wider industry view, consult our comprehensive 2026 Unified API Benchmark.

Quick-Start POC Checklist and Test Scenarios

The biggest mistake teams make is treating vendor evaluation as a feature checklist exercise. Both platforms have polished marketing pages and both will pass a surface-level POC. The real test is your specific edge case. Run the scenarios below during your proof-of-concept - they expose architectural differences faster than any demo.

POC Objective and Success Criteria

Define these before writing any test code. A POC without explicit exit criteria drags on for weeks and produces ambiguous verdicts.

Objective: Prove that the vendor can serve your top three integrations end-to-end (auth, read, write, reconcile) against a representative customer instance within the SLAs your product commits to.

Success criteria (minimum bar to green-light the vendor):

1. OAuth handshake completes in one round-trip per provider, with refresh tokens rotated automatically before expiry.
2. Reads return normalized responses matching your target schema. Custom fields surface via configuration, not code changes on the vendor side.
3. Writes complete synchronously with idempotent semantics. Failed writes return actionable, provider-attributable error codes.
4. Rate limit and pagination behavior is deterministic and documented in provider-agnostic terms.
5. Audit logs are queryable and exportable as SOC 2 or SOX evidence.
6. Data flow diagram maps every point where customer data touches vendor infrastructure - and, for zero-data-retention claims, proves the data does not persist.

Kill criteria (abort the POC):

• Any provider requires a vendor-side code change to expose a field your customer actually uses.
• Write failures surface as opaque 500s with no correlation ID or provider-side error context.
• The vendor cannot produce a data flow diagram showing where customer data is stored or passed through.
• Rate limit responses are silently swallowed, making your own circuit breakers impossible to tune.

Scenario 1: NetSuite Schema Drift and Custom Fields Test

What to test: Connect your hardest customer's NetSuite instance - ideally a OneWorld account with multi-currency, multi-subsidiary, and heavy customization on Purchase Orders (custom body fields like custbody42, custom column fields on line items, custom forms with hidden or mandatory field overrides).

Run the full round-trip:

1. List purchase orders and confirm the response includes custom body and column fields.
2. Read the field metadata for a specific custom PO form (subsidiary-scoped defaults, custom mandatory rules).
3. Create a purchase order that writes to a custom body field and includes line-item custom columns.
4. Download the resulting PO as a PDF.

Pass criteria:

• Multi-currency and multi-subsidiary detection happens automatically at connection time. The unified API adapts its underlying SuiteQL query shape without any client-side configuration.
• Custom fields (custbody*, custcol*) surface in the response without vendor engineering involvement. You can express a per-tenant JSONata override to promote a custom field into your unified schema.
• Form-scoped field metadata reflects the real runtime state - visible fields, mandatory flags, and dependent select options - not just static record schema.
• PDF generation works end-to-end (in NetSuite's case, via a SuiteScript Suitelet). If the vendor cannot produce PO PDFs at all, that is a category failure for AP automation products.

Scenario 2: Rate Limits and Pagination Stress Test

What to test: Run a bulk read against a rate-limited provider until you provoke throttling. Salesforce daily API caps, HubSpot 10-second burst windows, and NetSuite concurrency limits are reliable targets. In parallel, paginate through a large result set (10k+ records) to observe cursor behavior across the transition.

# Bulk read with cursor pagination
curl -H "Authorization: Bearer $TRUTO_TOKEN" \
  "https://api.truto.one/unified/accounting/invoices?integrated_account_id=acct_9f3&page_size=100"

Expected 200 response shape:

{
  "result": [ { "id": "inv_1", "total_amount": 1200.50, "status": "OPEN", "currency": "USD" } ],
  "next_cursor": "eyJvZmZzZXQiOjEwMH0=",
  "has_more": true
}

Expected 429 response headers when throttled:

HTTP/1.1 429 Too Many Requests
ratelimit-limit: 100
ratelimit-remaining: 0
ratelimit-reset: 12
x-truto-upstream-provider: salesforce

Pass criteria:

• Standardized ratelimit-* headers appear on every response, not just failures.
• 429s pass through transparently with the upstream provider identified. No silent retries that mask the failure and inflate perceived latency.
• The same pagination interface (next_cursor + has_more) works across every provider, even when the underlying provider uses offset, page-number, or cursor pagination internally.
• No cursor corruption when a page transition coincides with a rate limit event. Retrying with the same cursor after backoff resumes correctly.

Scenario 3: Write Reliability - Create → Apply Payment → Recover from Failed Write

What to test: The most common failure mode in accounting integrations is a partially completed write chain. Simulate the full order-to-cash flow, then deliberately fail one step.

Step 1 - Create an invoice:

curl -X POST -H "Authorization: Bearer $TRUTO_TOKEN" \
  "https://api.truto.one/unified/accounting/invoices?integrated_account_id=acct_9f3" \
  -H "Idempotency-Key: poc-invoice-2026-01-15-001" \
  -d '{
    "contact_id": "cust_882",
    "issue_date": "2026-01-15",
    "due_date": "2026-02-14",
    "currency": "USD",
    "line_items": [
      { "item_id": "item_54", "quantity": 2, "unit_price": 500.00, "account_id": "acct_revenue_01" }
    ]
  }'

Expected 201 response:

{
  "id": "inv_7c3",
  "status": "OPEN",
  "total_amount": 1000.00,
  "remote_id": "NS-PO-4421",
  "created_at": "2026-01-15T10:22:03Z"
}

Step 2 - Apply a payment to the invoice. Then intentionally break the third step (e.g., submit a malformed journal entry, or trigger a provider-side validation error) and observe recovery behavior.

Pass criteria:

• Idempotency keys are honored. Replaying the same Idempotency-Key returns the original resource, not a duplicate.
• Write failures return structured errors with the upstream provider's original error code preserved, plus a Truto correlation ID for support triage.
• No orphaned state. If step 3 fails, steps 1 and 2 do not need manual cleanup because they are addressable by remote_id on retry.
• Audit logs contain a row for every write attempt - successful and failed - with caller identity and payload hash.

Scenario 4: Passthrough and Raw Data Verification

What to test: For provider-specific data that does not fit a unified schema, confirm the platform exposes the raw upstream response without transformation. This is essential when your product needs a field the vendor has not modeled yet.

# Truto raw passthrough - proxy directly to the provider's native endpoint
curl -H "Authorization: Bearer $TRUTO_TOKEN" \
  "https://api.truto.one/proxy/netsuite/services/rest/query/v1/suiteql?integrated_account_id=acct_9f3" \
  -X POST -d '{ "q": "SELECT id, custbody42 FROM transaction WHERE type = '\''PurchOrd'\'' AND rownum <= 5" }'

Pass criteria:

• Raw response body matches what the provider would return if called directly.
• OAuth token injection and rate limit normalization still happen on passthrough calls - you should not have to re-implement auth to escape the unified schema.
• Passthrough calls appear in audit logs with the same fidelity as unified API calls.

Scenario 5: Data Freshness Under Load

What to test: Update a record in the upstream provider (e.g., change a deal stage in Salesforce). Immediately read it back through the unified API. Measure the latency between the write and when the read returns the updated value.

Pass criteria for pass-through: Updated value returned on the next read (sub-2s). Pass criteria for cache: Understand and document the actual sync delay for your use case.

Scenario 6: MCP Agent Tool Call (if applicable)

What to test: Create an MCP server scoped to read-only CRM tools. Connect it to Claude or a custom agent. Have the agent list contacts, then attempt a write operation. Confirm the write is blocked by method-level restrictions.

Pass criteria: The MCP server exposes only the tools matching your method and tag filters. Unauthorized operations return a clear error, not a silent failure. The agent receives live data, not a cached snapshot.

Scenario 7: Schema Gap Coverage

What to test: Request a resource that the standard unified schema does not cover (a non-standard Jira field type, a custom NetSuite record, a provider-specific endpoint). Determine if you can add it via configuration or if it requires a vendor roadmap commitment.

Pass criteria: You can ship the missing resource in days via configuration, not weeks via an engineering ticket.

Sample API Calls and Expected Responses

A condensed reference sheet you can drop into your POC repo:

List invoices (multi-provider, unified shape):

curl -H "Authorization: Bearer $TRUTO_TOKEN" \
  "https://api.truto.one/unified/accounting/invoices?integrated_account_id=acct_9f3&issue_date_gte=2026-01-01"

{
  "result": [
    {
      "id": "inv_7c3",
      "contact": { "id": "cust_882", "name": "Acme Corp" },
      "issue_date": "2026-01-15",
      "due_date": "2026-02-14",
      "status": "OPEN",
      "currency": "USD",
      "total_amount": 1000.00,
      "line_items": [
        { "item_id": "item_54", "quantity": 2, "unit_price": 500.00 }
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get a single contact with polymorphic type (NetSuite vendor vs customer):

curl -H "Authorization: Bearer $TRUTO_TOKEN" \
  "https://api.truto.one/unified/accounting/contacts/vend_44?integrated_account_id=acct_9f3&contact_type=vendor"

{
  "id": "vend_44",
  "name": "Widgets Supply Co",
  "contact_type": "vendor",
  "emails": [{ "email_address": "ap@widgetssupply.com", "type": "primary" }],
  "currency": "USD",
  "subsidiaries": [{ "id": "1", "is_primary": true }],
  "status": "active"
}

Structured error response on failed write:

{
  "error": {
    "code": "upstream_validation_failed",
    "message": "Purchase order line item missing required custcol_project_code",
    "upstream_provider": "netsuite",
    "upstream_error_code": "USER_ERROR",
    "correlation_id": "trt_req_01H8...",
    "retryable": false
  }
}

Security Sign-Off Checklist

Enterprise security teams will block your vendor selection if the integration platform cannot produce the right artifacts. This checklist covers what your InfoSec and compliance teams will ask for - prepare these answers before the review meeting, not after.

Compliance Checklist: Audit Logs, Encryption, Zero Data Retention

These three items are the ones a SOX or SOC 2 auditor will demand evidence for. Confirm each with the vendor in writing:

• Zero data retention proof. Ask the vendor to demonstrate architecturally that reads are not persisted. A proxy architecture returns customer data in the HTTP response and drops it from memory once the request completes. A sync-and-cache architecture cannot make this claim - it must instead document retention windows and deletion SLAs.
• Encryption in transit and at rest. TLS 1.2+ on every hop, AES-256 (or equivalent) for anything the vendor does store (OAuth refresh tokens, configuration, audit logs). Confirm key management: customer-managed keys, HSM-backed keys, or vendor-managed with rotation SLAs.
• Audit log completeness. Every API call, every MCP tool invocation, every credential access must be logged with caller identity, integrated account ID, resource path, timestamp, and outcome. Logs must be exportable to your SIEM (typically S3, Splunk, or Datadog).
• SOX-aligned change controls. For finance customers, any configuration change to a live integration (mapping override, resource addition, permission change) must be attributable to a named user and reversible.

Data Handling and Residency

• Data flow diagram: Can the vendor provide an architecture diagram showing exactly where customer data flows and whether it is stored, cached, or passed through?
• Data retention policy: Does the vendor store customer data? If yes, what is the retention period, encryption standard, and deletion process? If no (zero data retention), can they demonstrate this architecturally?
• Data residency options: Can the platform deploy in your required region (EU, specific country, on-prem) to satisfy GDPR, DORA, or sector-specific mandates?

Authentication and Access Control

• OAuth token lifecycle: How does the platform manage OAuth tokens for connected integrations? Are refresh tokens stored encrypted? Are access tokens refreshed proactively before expiry?
• MCP server authentication: Does the MCP endpoint support dual-layer auth (token URL + API key)? Can you enforce that possession of the URL alone is insufficient?
• Method-level restrictions: Can you restrict an MCP server or API scope to read-only, preventing agents or downstream consumers from performing destructive operations?
• Token expiration: Can MCP servers and API tokens be created with a TTL for time-bounded access?

Audit and Compliance Artifacts

• SOC 2 Type II report: Is it current and available under NDA?
• Penetration test results: When was the last third-party pentest? Can results be shared?
• OWASP MCP Top 10 posture: For MCP server deployments, how does the platform address tool poisoning (MCP03), token mismanagement (MCP01), and excessive permissions (MCP04)?
• Audit logging: Does the platform log every API call and MCP tool invocation with caller identity, resource accessed, and timestamp? Can logs be exported to your SIEM?
• Incident response SLA: What are the notification timelines for security incidents affecting customer data or credentials?

Agent-Specific Security

• Tool description integrity: Are MCP tool descriptions generated from curated documentation records, or can third parties inject arbitrary descriptions? (This directly mitigates OWASP MCP03 tool poisoning.)
• Scope isolation: Is each MCP server scoped to a single connected account, preventing cross-tenant data leakage?
• Rate limit passthrough: Does the platform surface upstream 429 errors transparently so your agent's circuit breakers can function, or does it silently retry and create unpredictable latency?

A Pragmatic Next Step

Integrating with the fragmented SaaS ecosystem is a complex, painful reality of modern software engineering. By choosing the architecture that matches your operational requirements - whether that is a specialized caching layer or a real-time execution engine - you can abstract the underlying mess and get back to building your core product.