Viacle API

Viacle is the commercial purchase intelligence layer between payment confirmation and ERP entry. It transforms ACH wires, commercial card transactions, freight invoices, and vendor bills into GL-coded, commodity-classified purchase objects — consistent schema, regardless of payment rail or source.

All responses are JSON. All requests must include an Authorization: Bearer header. The interactive version of these docs — with live code samples, a sidebar navigator, and a schema explorer — is at viacle.io/docs.

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer vi_live_sk_your_api_key

Key Security

Quickstart

One API call turns a vendor invoice, card transaction, or freight bill into a structured purchase object with GL code, vendor TIN, and line-item commodity codes. Get from zero to your first purchase object in under five minutes.

Step 1 — Create a purchase from an invoice URL

curl -X POST https://api.viacle.io/api/v1/purchases \
  -H "Authorization: Bearer vi_live_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_url": "https://example.com/invoice.pdf",
    "reference_id": "AP-2026-00831"
  }'

Step 2 — Receive the purchase object

{
  "id": "pur_vc_82af31",
  "object": "purchase",
  "status": "completed",
  "merchant": {
    "name": "Grainger Industrial Supply",
    "id": "mer_grngr",
    "category": "Industrial Supplies",
    "tin": "36-1165231",
    "registered_name": "W.W. Grainger, Inc."
  },
  "purchase_date": "2026-03-20",
  "amounts": { "subtotal": 2847.00, "tax": 227.76, "total": 3074.76, "currency": "USD" },
  "items": [
    {
      "name": "3M Nitrile Gloves CS",
      "quantity": 2,
      "price": 296.00,
      "sku": "GRW-7105-0232",
      "commodity_code": "46181500",
      "category": "Safety & PPE"
    },
    {
      "name": "Honeywell Respirator Half-Face",
      "quantity": 1,
      "price": 589.00,
      "sku": "GRW-8250-4120",
      "commodity_code": "46182001",
      "category": "Safety & PPE"
    }
  ],
  "expense": {
    "gl_code": "6400",
    "cost_center": "OPS-WEST",
    "approval_status": "pending_review"
  },
  "reportable_1099": false,
  "data_source": "ocr_extracted",
  "reference_id": "AP-2026-00831",
  "confidence": { "merchant": 0.99, "items": 0.94, "gl_code": 0.91 },
  "verification_url": "https://api.viacle.io/verify/pur_vc_82af31"
}

Step 3 — Retrieve it any time

curl https://api.viacle.io/api/v1/purchases/pur_vc_82af31 \
  -H "Authorization: Bearer vi_live_sk_your_api_key"

Rate Limits

The Retry-After header on a 429 response indicates when the window resets. Enterprise plans carry higher or custom limits — contact the Viacle team to discuss volume requirements.

Error Codes

All errors follow a consistent envelope: { "error_code": "...", "message": "...", "trace_id": "..." }.

The Purchase Object

Every purchase processed by Viacle becomes a persistent, programmable object. The schema is deterministic: every top-level field is always present, even when the value is null. The full annotated schema with lifecycle diffs and webhook event payloads is at viacle.io/object.

Create Purchase POST /purchases

Create a purchase object from a document URL, structured transaction metadata, or raw text. Returns the complete purchase object synchronously for most requests; large PDFs trigger an async extraction job and return status: "processing".

// From a document URL
{
  "document_url": "https://your-domain.com/invoices/INV-2026-0041.pdf",
  "reference_id":  "AP-2026-00831",
  "entity_id":     "ent_acme_corp"
}

// From structured transaction metadata
{
  "merchant_name": "WEX Fleet Services",
  "total":         1847.30,
  "currency":      "USD",
  "purchase_date": "2026-03-20",
  "payment_method": { "type": "fleet", "last_four": "4421" },
  "reference_id":  "TXN-88321"
}

// AP invoice ingest (alternate endpoint — see below)
POST /purchases/ingest
{
  "vendor_name":   "Turner Mechanical LLC",
  "invoice_number":"INV-TM-0441",
  "po_number":     "PO-2026-0814",
  "line_items": [
    { "description": "HVAC Ductwork Zone B", "amount": 18400.00, "quantity": 1 }
  ],
  "total": 18400.00,
  "currency": "USD"
}

AP Invoice Ingest POST /purchases/ingest

AP-workflow-focused alternative to POST /purchases. Accepts vendor name, line items, PO reference, and payment terms using vocabulary AP teams already use. Returns the normalized purchase object with a commercial block and an ingest_summary envelope covering GL assignment, match status, and data completeness.

Get Purchase GET /purchases/:id

curl https://api.viacle.io/api/v1/purchases/pur_vc_82af31 \
  -H "Authorization: Bearer vi_live_sk_your_api_key"

Returns the full purchase object. Also accepts GET /purchases?reference_id=AP-2026-00831 to look up by your reference ID.

List Purchases GET /purchases

Returns a paginated list of purchases. Query parameters:

Update Purchase PATCH /purchases/:id

Update mutable fields on an existing purchase object. Commonly used to set or update GL codes, approval status, and cost center after creation.

{
  "expense": {
    "gl_code":         "6400",
    "cost_center":     "OPS-WEST",
    "approval_status": "approved",
    "approved_by":     "jane.doe@company.com"
  }
}

Patchable fields: merchant_name, purchase_date, total, items, expense (entire block), entity_id, reference_id, locale, receipt_medium. Patching emits a purchase.updated webhook event.

Delete Purchase DELETE /purchases/:id

Soft-deletes a purchase record. The object is removed from all list and query endpoints immediately. Per-key data retention policy determines when the record is permanently purged. Requires the purchases:write scope.

Complete Endpoint Reference

This inventory is generated directly from /openapi.json. It contains 178 documented operations across 142 paths. The machine-readable contract is authoritative for methods, request schemas, response codes, and required scopes.

Generated Schemas

These component schemas are rendered from the same OpenAPI contract as the endpoint inventory. Narrative guidance above explains common workflows; this section is the authoritative field reference.

Webhooks

Register an HTTPS endpoint to receive real-time events. Viacle delivers events with a signed X-Viacle-Signature header (HMAC-SHA256 of the raw request body).

Register a webhook endpoint

{
  "url":    "https://your-server.com/webhooks/viacle",
  "events": ["purchase.created", "purchase.updated", "purchase.gl_coded"]
}

Signature verification (Node.js)

const crypto = require("crypto");

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const received = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

Event types

API Scopes

Every API key carries an explicit scope list. A key is only permitted to call endpoints within its granted scopes.

Connectors

Viacle connects to 50+ data sources via push connectors (webhooks), pull connectors (scheduled sync), and structured format parsers. Each connector normalizes its source format into the same purchase object schema. The full interactive connector list is at viacle.io/docs.

Idempotency

Pass an Idempotency-Key header on POST /purchases to make creation safe to retry. Duplicate requests within the deduplication window return the original response without creating a second record.

Idempotency-Key: your-unique-key-ap-2026-00831

The reference_id field provides a secondary deduplication layer: if a purchase with the same reference_id already exists under your API key, the endpoint returns 409 CONFLICT.

Security & Data Handling