SDK QUICKSTART

POST YOUR
FIRST MATCH.

Send a three-way-match request to Truss from Python or Node.js with a bearer token, a JSON body, and no SDK package to install. Get a key from /developers, then compare this page with the full POST /api/agents API reference or use the API error reference when a response is unsuccessful.

01

THE REQUEST

Set TRUSS_API_KEY in your environment. Every request needs Authorization: Bearer <key> and Content-Type: application/json. The examples use the live three_way_match contract: a PO with po_number, amount, vendor_name, and date, plus invoice and receipt with amount, vendor_name, and date.

TRUSS_WEBHOOK_URL is optional. When it is set, the examples add webhook_url to this request; when it is unset, they omit the field and leave any stored callback unchanged.

02

SDK EXAMPLES

Choose a language, export your key, and run the complete authenticated request as-is.

Install the commonly available requests library once, export your key, and run the script as-is. 

python -m pip install requests

three_way_match.py

import json
import os
import sys

import requests

API_URL = "https://api.truss.polsia.app/api/agents"
api_key = os.environ["TRUSS_API_KEY"]
webhook_url = os.getenv("TRUSS_WEBHOOK_URL")

payload = {
    "mode": "three_way_match",
    "po": {
        "po_number": "PO-001",
        "amount": 100.00,
        "vendor_name": "Acme Software Ltd",
        "date": "2026-08-29",
    },
    "invoice": {
        "amount": 100.00,
        "vendor_name": "Acme Software Ltd",
        "date": "2026-08-29",
    },
    "receipt": {
        "amount": 100.00,
        "vendor_name": "Acme Software Ltd",
        "date": "2026-08-29",
    },
}

if webhook_url:
    payload["webhook_url"] = webhook_url

response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)

if not response.ok:
    print(f"Truss returned HTTP {response.status_code}: {response.text}", file=sys.stderr)
    response.raise_for_status()

print(json.dumps(response.json(), indent=2))
04

THE RESPONSE

A valid API key returns 200 even when the documents do not match. Read the top-level authenticated and owner_label, then inspect the nested verification object. Its verdict is missing, verified, partial, or mismatch. 

{
  "authenticated": true,
  "owner_label": "your-key-label",
  "verification": {
    "mode": "three_way_match",
    "verdict": "verified",
    "verified": true,
    "missing_documents": [],
    "comparisons": [
      { "field": "amount", "matched": true, "values": { "po": 100, "invoice": 100, "receipt": 100 } },
      { "field": "vendor_name", "matched": true, "values": { "po": "Acme Software Ltd", "invoice": "Acme Software Ltd", "receipt": "Acme Software Ltd" } },
      { "field": "date", "matched": true, "values": { "po": "2026-08-29", "invoice": "2026-08-29", "receipt": "2026-08-29" } }
    ],
    "matched_fields": [
      { "field": "amount", "values": { "po": 100, "invoice": 100, "receipt": 100 } },
      { "field": "vendor_name", "values": { "po": "Acme Software Ltd", "invoice": "Acme Software Ltd", "receipt": "Acme Software Ltd" } },
      { "field": "date", "values": { "po": "2026-08-29", "invoice": "2026-08-29", "receipt": "2026-08-29" } }
    ],
    "anomalies": [],
    "checked_at": "2026-08-29T12:00:00.000Z"
  }
}

When a valid webhook_url is active, the inline 200 response is unchanged except for a top-level tier field. The same envelope is posted to your callback asynchronously; the nested verification result does not change. 

{
  "tier": "paid"
}
05

WEBHOOK NOTES

webhook_url accepts a credential-free http:// or https:// URL and is persisted per API key. Omit it on later requests to reuse the stored callback. To clear the stored callback deliberately, send "webhook_url": null; the examples omit the field when TRUSS_WEBHOOK_URL is not configured so they do not accidentally clear or overwrite an existing callback.

See the full API reference for accepted authentication alternatives, callback signatures, retry behavior, and the complete request field list. For the exact error bodies and corrective actions, see the API error reference.