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

No issue requires review under your chosen settings. Check for any remaining warnings.

"validation.review_required": false

applyYourBusinessPolicy(result);

needs_review

Invoice data is available, but an issue needs attention. Send the result to your review step.

"validation.review_required": true

routeToYourReviewStep(result);

failed

No usable invoice data was returned. 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 submission. The SDK snapshots create options for retries; preserve those options, the source bytes and the same idempotency key when recovering an interrupted logical submission. Changing policy under the same live 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 retrying one logical submission with its existing idempotency key.

Exit 0 means Temlavo returned a terminal document: its status may be completed, needs_review, or failed. Inspect .status before continuing. Non-zero means a local, transport, synchronous API, or orchestration error prevented the normal terminal-document outcome.

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.