EVA API reference: expense receipt analysis
The EVA API is a REST API that submits an expense receipt (invoice, till receipt, PDF or photo) to EVA's AI analysis and returns a compliance verdict, the data read from the receipt and the result of every check. You can call it from any tool: expense management software, an ERP, an internal portal or an auditor's browser extension.
Overview
Each customer has its own EVA workspace, isolated from the others. The base URL contains the workspace name, given at onboarding, for instance https://acme.tevasoft.io/api/v1. An API key only works on the workspace that issued it.
Analysis is asynchronous: reading the receipt (OCR) and running the checks takes from a few seconds to a minute. The submission answers immediately with an identifier and a status_url, which you poll until the analysis ends.
https://{workspace}.tevasoft.io/api/v1Lifecycle of an analysis
1.Categories
GET /categories/ returns the expense categories of your workspace, to cache.
2.Submission
POST /analyses/ with the file, category and employee: 202 response and status_url.
3.Analysis
EVA reads the receipt (status reading), then runs the category checks (analysing).
4.Result
GET the status_url: once status is done, the response holds the verdict, extracted data and checks.
Conventions
- URLs end with a slash: /analyses/, /analyses/{id}/.
- Identifiers (analyses, categories) are UUIDs. Dates use YYYY-MM-DD; timestamps use ISO 8601 with a time zone.
- New fields, statuses or checks may be added without a version change: ignore the ones you do not know. No field will be removed or renamed in v1.
- Messages are written for a human reader, in the workspace language. Build your logic on status, verdict, code and severity, never on messages.
Authentication
Every call carries an API key in the Authorization: Bearer header. Keys start with eva_ and are created in EVA, under Config > API access. A key belongs to the user who creates it and acts with their rights: they need an audit role that sees every employee’s expenses.
The key is shown only once, when created: EVA stores only a hash. Keep it in your secrets store, never in code that runs in the browser. Keys do not expire; revoke a key from the same screen as soon as it is no longer used or may have leaked. A user has at most 10 active keys, and a deactivated account loses access immediately.
curl https://{workspace}.tevasoft.io/api/v1/categories/ \
-H "Authorization: Bearer $EVA_API_KEY"import os, requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['EVA_API_KEY']}"
BASE_URL = "https://acme.tevasoft.io/api/v1"const BASE_URL = "https://acme.tevasoft.io/api/v1";
const headers = { Authorization: `Bearer ${process.env.EVA_API_KEY}` };$baseUrl = 'https://acme.tevasoft.io/api/v1';
$headers = ['Authorization: Bearer ' . getenv('EVA_API_KEY')];List categories
Returns the expense categories of your workspace, sorted by name. Each analysis belongs to a category, which decides the checks applied and any spending cap. Categories rarely change: cache the list and refresh it once a day.
| Field | Type | Description |
|---|---|---|
| id | uuid | Identifier to send in the category field of a submission. |
| name | string | Category name in EVA. |
| max_amount | number | null | Cap set for the category, null when there is none. |
curl https://{workspace}.tevasoft.io/api/v1/categories/ \
-H "Authorization: Bearer $EVA_API_KEY"response = session.get(f"{BASE_URL}/categories/", timeout=10)
response.raise_for_status()
categories = {c["name"]: c["id"] for c in response.json()["categories"]}const response = await fetch(`${BASE_URL}/categories/`, { headers });
if (!response.ok) throw new Error(`EVA ${response.status}`);
const { categories } = await response.json();$ch = curl_init("$baseUrl/categories/");
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true]);
$categories = json_decode(curl_exec($ch), true)['categories'];
curl_close($ch);{
"categories": [
{ "id": "1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11", "name": "Hotel", "max_amount": 180.0 },
{ "id": "4e2a9d07-3c6b-4f85-a1d9-0b8e7c5f2a64", "name": "Business meals", "max_amount": null },
{ "id": "9c3e5b18-7d2f-4a60-b4e1-6a9f0d2c8b75", "name": "Train", "max_amount": null }
]
}Submit a receipt
Submits a receipt for analysis. The request is multipart/form-data, with flat fields (no nested JSON object).
| Field | Type | Description |
|---|---|---|
| file | file | Required. PDF, JPEG or PNG, 15 MB max, images up to 50 megapixels. The declared type must match the actual file content. |
| category | uuid | Required. Identifier of a category returned by GET /categories/. |
| employee_external_id | string | Required, 46 characters max. Your stable employee identifier: employee number, ID in your tool. |
| employee_first_name | string | Required. Employee's first name. |
| employee_last_name | string | Required. Employee's last name. |
| employee_email | string | Optional. Employee's email. |
curl -X POST https://{workspace}.tevasoft.io/api/v1/analyses/ \
-H "Authorization: Bearer $EVA_API_KEY" \
-F "file=@hotel-invoice-lyon.pdf;type=application/pdf" \
-F "category=1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11" \
-F "employee_external_id=E004217" \
-F "employee_first_name=Claire" \
-F "employee_last_name=Martin" \
-F "employee_email=claire.martin@example.com"with open("hotel-invoice-lyon.pdf", "rb") as receipt:
response = session.post(
f"{BASE_URL}/analyses/",
files={"file": ("hotel-invoice-lyon.pdf", receipt, "application/pdf")},
data={
"category": "1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11",
"employee_external_id": "E004217",
"employee_first_name": "Claire",
"employee_last_name": "Martin",
"employee_email": "claire.martin@example.com",
},
timeout=30,
)
response.raise_for_status()
analysis = response.json() # {"id": ..., "status": "reading", "status_url": ...}import { readFile } from "node:fs/promises";
const form = new FormData();
const pdf = await readFile("hotel-invoice-lyon.pdf");
form.append("file", new Blob([pdf], { type: "application/pdf" }), "hotel-invoice-lyon.pdf");
form.append("category", "1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11");
form.append("employee_external_id", "E004217");
form.append("employee_first_name", "Claire");
form.append("employee_last_name", "Martin");
form.append("employee_email", "claire.martin@example.com");
const response = await fetch(`${BASE_URL}/analyses/`, { method: "POST", headers, body: form });
const analysis = await response.json(); // 202 (new) or 200 (same receipt already submitted)$ch = curl_init("$baseUrl/analyses/");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => [
'file' => new CURLFile('hotel-invoice-lyon.pdf', 'application/pdf'),
'category' => '1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11',
'employee_external_id' => 'E004217',
'employee_first_name' => 'Claire',
'employee_last_name' => 'Martin',
'employee_email' => 'claire.martin@example.com',
],
]);
$analysis = json_decode(curl_exec($ch), true);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 202 or 200
curl_close($ch);HTTP/1.1 202 Accepted
Content-Type: application/json
{
"id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
"status": "reading",
"status_url": "https://acme.tevasoft.io/api/v1/analyses/6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13/"
}The employee
EVA identifies the employee by employee_external_id, never by name: two people with the same name stay distinct. Your tool is the source of truth: if the name or email changed since the previous submission, EVA updates them. The name is used to check that a named invoice is in the employee's name, and the employee's history is used to detect duplicates. An employee excluded from analysis in EVA (Config > Excluded employees) is rejected with a 422 error.
Submitting the same receipt again
If the same file is submitted for the same employee and category within 10 minutes, EVA creates no second analysis and does not read the document again: it answers 200 with the existing analysis. A new submission answers 202. You can therefore replay an interrupted call without creating a duplicate or paying for a second analysis.
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
"status": "done",
"status_url": "https://acme.tevasoft.io/api/v1/analyses/6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13/"
}Where the analysis shows up in EVA
Each submission creates an expense report in EVA, visible to auditors in the expense report list, with a direct link in the web_url field. It lives outside your expense tool: EVA writes nothing back to SAP Concur or any other connected tool, and takes no approval decision on an analysis submitted through the API.
Retrieve an analysis
Returns the state of an analysis. Poll the status_url received at submission every 2 to 5 seconds while status is reading or analysing. Any key of the workspace can read any analysis submitted through the API in that workspace.
curl https://{workspace}.tevasoft.io/api/v1/analyses/6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13/ \
-H "Authorization: Bearer $EVA_API_KEY"analysis = session.get(analysis["status_url"], timeout=10).json()
print(analysis["status"], analysis.get("verdict"))const current = await fetch(analysis.status_url, { headers }).then((r) => r.json());
console.log(current.status, current.verdict);$ch = curl_init($analysis['status_url']);
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true]);
$current = json_decode(curl_exec($ch), true);
curl_close($ch);{
"id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
"status": "analysing",
"category": "Hotel",
"created_at": "2026-11-17T09:12:44.310152+01:00",
"web_url": "https://acme.tevasoft.io/…"
}{
"id": "6f1c2b0e-3d4a-4f7e-9a51-8c2d7e0b9f13",
"status": "done",
"category": "Hotel",
"created_at": "2026-11-17T09:12:44.310152+01:00",
"web_url": "https://acme.tevasoft.io/…",
"verdict": "failed",
"extracted": {
"total_amount": 214.6,
"currency": "EUR",
"invoice_date": "2026-11-12",
"establishment": "Riverside Hotel",
"invoice_number": "F-2026-08812",
"document_type": "invoice"
},
"checks": [
{
"code": "duplicate_check",
"label": "Duplicate",
"passed": false,
"severity": "failed",
"error_code": "…",
"message": "Receipt already submitted in another expense report.",
"warning": ""
},
{
"code": "nominative_invoice_check",
"label": "Named invoice",
"passed": true,
"severity": "passed",
"error_code": null,
"message": "",
"warning": ""
}
]
}{
"id": "0c9d4e21-5b7a-4c3f-8e16-2d9a7f4b1c58",
"status": "unreadable",
"category": "Business meals",
"created_at": "2026-11-17T10:03:12.004871+01:00",
"web_url": "https://acme.tevasoft.io/…"
}The Analysis object
The verdict, extracted and checks fields only appear when status is done. Before that they would be partial and could make an incomplete expense look compliant.
| Field | Type | Description |
|---|---|---|
| id | uuid | Analysis identifier. |
| status | string | Processing state, see Statuses. |
| category | string | null | Category name. |
| created_at | datetime | Submission time. |
| web_url | string | Link to the expense report in EVA, for a signed-in auditor. |
| verdict | string | When done. passed, failed (anomaly) or manual_review (needs review). |
| extracted.total_amount | number | null | Total amount read on the receipt. |
| extracted.currency | string | null | Currency, ISO 4217 code. |
| extracted.invoice_date | date | null | Receipt date. |
| extracted.establishment | string | null | Merchant name. |
| extracted.invoice_number | string | null | Invoice number. |
| extracted.document_type | string | null | Document type recognised (invoice, receipt…). |
| checks | array | When done. Result of every check, anomalies first. |
Statuses
status tells where processing stands. Only reading and analysing are transient: stop polling on any other value.
| status | Meaning | What to do |
|---|---|---|
| reading | EVA is reading the receipt (OCR). | Poll again. |
| analysing | The category checks are running. | Poll again. |
| done | Analysis complete: verdict, extracted and checks are present. | Read the verdict. |
| unreadable | The receipt could not be read (empty, too blurry, illegible). | Ask for a better receipt and submit it again. |
| not_applicable | No check applies to this analysis. | Handle it outside EVA. |
| frozen | Analysis is paused on the EVA side, for instance during maintenance. | Poll again later: it will resume. |
| stalled | No progress for 15 minutes. | Submit again or contact support with the id. |
Checks and verdict
checks lists the checks configured in EVA for the category, out of more than 45: duplicates, receipt compliance, named invoice, caps, date and amount consistency, signs of tampering. Checks an auditor has dismissed, or that have since been disabled, are not returned.
| Field | Type | Description |
|---|---|---|
| code | string | Stable check identifier, for instance duplicate_check. The list of active checks is visible in your EVA workspace. |
| label | string | Check name. |
| passed | boolean | True when the check is compliant. |
| severity | string | passed, failed (confirmed anomaly) or manual_review (doubt: an auditor must decide). |
| error_code | string | null | Anomaly reason, when the check provides one. |
| message | string | Explanation of the anomaly, empty when the check passed. |
| warning | string | Additional warning, even on a passed check. |
The verdict
verdict sums up the analysis: passed when every check is compliant, failed when at least one anomaly is confirmed, manual_review when a doubt remains for an auditor to resolve. EVA flags; your process decides whether to approve, send back or reject the expense.
Turning the result into an action
One way to map the EVA result to the next step of your approval workflow:
// One way to turn an EVA analysis into an action in your workflow.
function nextStep(analysis) {
switch (analysis.status) {
case "done":
if (analysis.verdict === "passed") return "approve";
if (analysis.verdict === "manual_review") return "send_to_auditor";
return "send_back_to_employee"; // failed: at least one confirmed anomaly
case "unreadable":
return "ask_for_a_better_receipt";
case "frozen":
return "retry_later";
default: // not_applicable, stalled
return "send_to_auditor";
}
}# One way to turn an EVA analysis into an action in your workflow.
def next_step(analysis: dict) -> str:
status = analysis["status"]
if status == "done":
return {
"passed": "approve",
"manual_review": "send_to_auditor",
"failed": "send_back_to_employee",
}[analysis["verdict"]]
if status == "unreadable":
return "ask_for_a_better_receipt"
if status == "frozen":
return "retry_later"
return "send_to_auditor" # not_applicable, stalledIntegration examples
These two complete programs submit a receipt, wait for the analysis while respecting rate limits, then print the verdict and anomalies. Replace acme with your workspace name and set the EVA_API_KEY environment variable.
Submit, wait, read the verdict
"""Submit an expense receipt to EVA and wait for the verdict."""
import os, time
import requests
BASE_URL = "https://acme.tevasoft.io/api/v1"
TRANSIENT = {"reading", "analysing"}
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['EVA_API_KEY']}"
def call(method, url, **kwargs):
"""HTTP call that waits and retries on 429 (rate limit)."""
for attempt in range(5):
response = session.request(method, url, timeout=30, **kwargs)
if response.status_code != 429:
response.raise_for_status()
return response.json()
time.sleep(2 ** attempt)
response.raise_for_status()
def analyse_receipt(path, category_id, employee):
with open(path, "rb") as receipt:
submitted = call(
"POST", f"{BASE_URL}/analyses/",
files={"file": (os.path.basename(path), receipt, "application/pdf")},
data={"category": category_id, **{f"employee_{k}": v for k, v in employee.items()}},
)
deadline = time.time() + 300
while time.time() < deadline:
analysis = call("GET", submitted["status_url"])
if analysis["status"] not in TRANSIENT:
return analysis
time.sleep(3)
raise TimeoutError(submitted["status_url"])
analysis = analyse_receipt(
"hotel-invoice-lyon.pdf",
"1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11",
{"external_id": "E004217", "first_name": "Claire", "last_name": "Martin"},
)
if analysis["status"] != "done":
print("No verdict:", analysis["status"])
elif analysis["verdict"] == "passed":
print("Compliant", analysis["extracted"]["total_amount"], analysis["extracted"]["currency"])
else:
for check in analysis["checks"]:
if not check["passed"]:
print(check["severity"], check["code"], check["message"])// Submit an expense receipt to EVA and wait for the verdict (Node.js 18+).
import { readFile } from "node:fs/promises";
import { basename } from "node:path";
const BASE_URL = "https://acme.tevasoft.io/api/v1";
const headers = { Authorization: `Bearer ${process.env.EVA_API_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(url, init = {}) {
for (let attempt = 0; attempt < 5; attempt++) {
const response = await fetch(url, { ...init, headers });
if (response.status === 429) { await sleep(1000 * 2 ** attempt); continue; }
if (!response.ok) throw new Error(`EVA ${response.status}: ${await response.text()}`);
return response.json();
}
throw new Error("EVA rate limit");
}
export async function analyseReceipt(path, categoryId, employee) {
const form = new FormData();
form.append("file", new Blob([await readFile(path)], { type: "application/pdf" }), basename(path));
form.append("category", categoryId);
for (const [key, value] of Object.entries(employee)) form.append(`employee_${key}`, value);
const submitted = await call(`${BASE_URL}/analyses/`, { method: "POST", body: form });
const deadline = Date.now() + 300_000;
while (Date.now() < deadline) {
const analysis = await call(submitted.status_url);
if (!["reading", "analysing"].includes(analysis.status)) return analysis;
await sleep(3000);
}
throw new Error(`Timeout: ${submitted.status_url}`);
}
const analysis = await analyseReceipt("hotel-invoice-lyon.pdf", "1b7f0c52-9a4e-4d1f-8c2e-5f0a6b3d9e11", {
external_id: "E004217", first_name: "Claire", last_name: "Martin",
});
const anomalies = (analysis.checks ?? []).filter((check) => !check.passed);
console.log(analysis.status, analysis.verdict, anomalies.map((check) => check.code));Errors
Validation errors return an errors object whose keys are the fields at fault and whose values are lists of messages (non_field_errors for a general error). Authentication, permission and per-key rate errors return a detail object.
| HTTP | Cause |
|---|---|
| 400 | Missing or invalid field: unknown category, unsupported file, content not matching the declared type, image too large. |
| 401 | Missing, invalid or revoked key, or deactivated account. |
| 403 | API not enabled for the workspace, or user without audit rights on all expenses. |
| 404 | Unknown analysis in this workspace. |
| 411 | Request without a Content-Length header. |
| 413 | Request larger than 15 MB. |
| 422 | Employee excluded from EVA analysis. |
| 429 | Rate limit or daily cap reached. |
HTTP/1.1 400 Bad Request
{
"errors": {
"category": ["Unknown category."],
"employee_last_name": ["This field is required."]
}
}HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
{ "detail": "Invalid or revoked token." }HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"employee_external_id": ["This person is excluded from EVA analysis."]
}
}HTTP/1.1 429 Too Many Requests
{
"errors": {
"non_field_errors": ["Daily analysis cap reached."]
}
}Limits
- Submissions: 30 per minute per key.
- Reads (categories, analyses): 300 per minute per key.
- Workspace daily cap: 1,000 submissions per day by default, adjustable on request. It protects against a leaked key; it is not a commercial quota.
- File: 15 MB max; PDF, JPEG or PNG; images up to 50 megapixels.
- Employee: identifier of 46 characters max.
Beyond that, the API answers 429: wait before retrying, with an increasing delay (see the integration examples).
Security and audit trail
- Call the API from your server. It does not allow direct calls from a web page (no CORS); a browser extension calls it from its service worker.
- Returned data (merchant name, messages) comes from the submitted receipt: escape it before displaying it.
- Every submission is logged in EVA with the prefix of the key used, as is every rejected key and every key creation or revocation. Changes to an employee’s name or email are logged without copying their values.
- Employee personal data is encrypted at rest, and receipts are stored in the customer’s isolated workspace.
FAQ
What is the EVA API?
+
A REST API that submits an expense receipt to EVA's AI analysis and returns a compliance verdict (passed, failed or manual_review), the data read from the receipt (amount, currency, date, merchant, invoice number) and the result of every check applied.
Which tools can call the EVA API?
+
Any software that can send an HTTPS request: expense management tools, ERPs, internal portals, browser extensions or scripts. For SAP Concur, N2F, Lucca and Cegid, EVA also has native connectors that analyse expense reports with no development.
How do I get an EVA API key?
+
A user with an audit role creates it in EVA, under Config > API access. The key starts with eva_ and is shown only once. The API comes with EVA's expense audit module.
How long does an analysis take?
+
From a few seconds to a minute per receipt. The submission answers immediately with a status_url, to poll every 2 to 5 seconds until status is no longer reading or analysing.
Which receipt formats are accepted?
+
PDF, JPEG and PNG, up to 15 MB and 50 megapixels per image. The file content must match the declared type.
Does the API change expense reports in SAP Concur or another tool?
+
No. An analysis submitted through the API creates an expense report in EVA only. EVA writes nothing to the expense tool and takes no approval decision: the calling tool decides what happens next.
What happens if a receipt is sent twice?
+
If the same file is submitted for the same employee and category within 10 minutes, EVA returns the existing analysis (status code 200) without creating a new one. After that, EVA's duplicate detection flags the second submission of the receipt.
Does the EVA API send webhooks?
+
Not in version 1. You read the result by polling the status_url returned at submission.
Is there an OpenAPI specification of the EVA API?
+
Yes, in OpenAPI 3.1 format, downloadable from this page. Use it to generate a client in most languages or to import the API into Postman.
Further reading
Get API access
The API comes with EVA's expense audit module. Write to us to open a test workspace and create your first keys.
Contact us