Submit an invoice and wait for the result.

Process an invoice with TypeScript

import { readFile } from 'node:fs/promises';
import { InvoiceClient } from '@temlavo/sdk';

const client = new InvoiceClient({
  apiKey: process.env.INVOICE_API_KEY!,
});

const file = await readFile('./invoice.pdf');
const result = await client.documents.process({
  file,
  filename: 'invoice.pdf',
  contentType: 'application/pdf',
});

if (result.status === 'completed') {
  // continue automation
} else if (result.status === 'needs_review') {
  // stop and route for review
} else {
  // terminal processing failure
}

Install @temlavo/sdk@1 for a project that accepts compatible 1.x updates. An explicit baseUrl or INVOICE_API_BASE_URL is only for controlled development and testing.

Handle results and review

completed

A usable result with no blocking check. Warnings may remain. Check them before you apply your rules.

"validation.review_required": false

applyYourBusinessPolicy(result);

needs_review

A usable result with at least one blocking check. Send the result to your review step.

"validation.review_required": true

routeToYourReviewStep(result);

failed

No usable result was produced. This status is final. Check the error code to decide what to do next. Processing failures are not billed.

"status": "failed"

handleFailure(error.code);

Branch primarily on status, validation.review_required, check status/severity, and paths. Known diagnostic codes have IDE autocomplete, but a future unknown non-empty code must be preserved and handled through those stable fallback fields.

Read the accounting data and review checks

Accounting fields are directly accessible under data. Use getBlockingChecks(), getReviewReasons(), and getWarnings() to read the server checks. The SDK does not make a second review decision.

AI selects explicit currency or infers it from invoice context by default. No country hints, templates, or inference option are needed. Truly unresolved currency remains null and can require review.

data.line_items_status is the AI assessment of item extraction: complete, partial, or unavailable. It is not a guarantee that every source item was captured. Missing optional item details do not block a useful header result.

Completed means processing finished without a blocking declared check. Values are not independently verified against OCR; arithmetic passes mean returned operands reconcile, not that extraction is factually correct, tax compliant, or authorized for payment.

Processing invoices for multiple clients

const result = await client.documents.process({
  file,
  filename: 'invoice.pdf',
  contentType: 'application/pdf',
  accountingEntityId: 'client_acme',
});

accountingEntityId is an optional opaque caller-defined namespace. Duplicate detection is isolated within it and usage can be attributed by it, but one Temlavo account still has one pooled Trial or subscription allowance. It is not an authorization boundary, subaccount, or separate billing account.

Configure document policy

const result = await client.documents.process({
  file,
  filename: 'invoice.pdf',
  contentType: 'application/pdf',
  policy: {
    requiredFields: ['/data/invoice/purchase_order_number'],
    lineItems: 'required',
    checks: { duplicateDetection: true },
  },
});

The SDK accepts the complete policy model with camelCase input names. The same options work with submit() and each processMany() item; returned resources keep the API’s snake_case names. Understand all review policy settings

Choose the policy before you submit. The SDK reuses the same create options on its own retries. When you resume an interrupted submission yourself, keep the same options, the same file and the same idempotency key. Changing policy under the same key returns idempotency_conflict. Keep fixture requests and keys as provided by their manifest, including omitted policy members.

Use the command line

INVOICE_API_KEY=inv_live_your_key \
  npm exec --yes --package=@temlavo/sdk@1 -- \
  temlavo process ./invoice.pdf

The CLI exposes --line-items, repeatable --required-field and --duplicate-detection true|false. These options apply to every file in the invocation. Duplicate detection is enabled by default. For example:

npm exec --yes --package=@temlavo/sdk@1 -- \
  temlavo process ./invoice.pdf --line-items required \
  --required-field /data/invoice/purchase_order_number

For intentional resubmission, add --duplicate-detection false. Use exact lowercase true or false; invalid or missing values fail locally. Keep the same policy when you retry an invoice with its existing idempotency key.

Exit 0 means Temlavo returned a finished document: its status may be completed, needs_review, or failed. Inspect .status before continuing. A non-zero exit means something stopped the CLI before it got a finished document: a local problem, a network error, or an API error.

CLI output may contain invoice data. Avoid saving it in shared CI logs, chat, monitoring tools, or debug files unless those systems are meant to retain it.