Developers · API v1

    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.

    Base URL
    https://{workspace}.tevasoft.io/api/v1

    Lifecycle of an analysis

    1. 1.Categories

      GET /categories/ returns the expense categories of your workspace, to cache.

    2. 2.Submission

      POST /analyses/ with the file, category and employee: 202 response and status_url.

    3. 3.Analysis

      EVA reads the receipt (status reading), then runs the category checks (analysing).

    4. 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"

    List categories

    GET/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.

    FieldTypeDescription
    iduuidIdentifier to send in the category field of a submission.
    namestringCategory name in EVA.
    max_amountnumber | nullCap set for the category, null when there is none.
    curl https://{workspace}.tevasoft.io/api/v1/categories/ \
      -H "Authorization: Bearer $EVA_API_KEY"
    Response
    {
      "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

    POST/analyses/

    Submits a receipt for analysis. The request is multipart/form-data, with flat fields (no nested JSON object).

    FieldTypeDescription
    filefileRequired. PDF, JPEG or PNG, 15 MB max, images up to 50 megapixels. The declared type must match the actual file content.
    categoryuuidRequired. Identifier of a category returned by GET /categories/.
    employee_external_idstringRequired, 46 characters max. Your stable employee identifier: employee number, ID in your tool.
    employee_first_namestringRequired. Employee's first name.
    employee_last_namestringRequired. Employee's last name.
    employee_emailstringOptional. 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"
    Response
    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.

    Response when the same receipt was already submitted
    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

    GET/analyses/{id}/

    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"
    Response while the analysis runs
    {
      "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/…"
    }
    Response once the analysis is done
    {
      "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": ""
        }
      ]
    }
    Response when the receipt is unreadable
    {
      "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.

    FieldTypeDescription
    iduuidAnalysis identifier.
    statusstringProcessing state, see Statuses.
    categorystring | nullCategory name.
    created_atdatetimeSubmission time.
    web_urlstringLink to the expense report in EVA, for a signed-in auditor.
    verdictstringWhen done. passed, failed (anomaly) or manual_review (needs review).
    extracted.total_amountnumber | nullTotal amount read on the receipt.
    extracted.currencystring | nullCurrency, ISO 4217 code.
    extracted.invoice_datedate | nullReceipt date.
    extracted.establishmentstring | nullMerchant name.
    extracted.invoice_numberstring | nullInvoice number.
    extracted.document_typestring | nullDocument type recognised (invoice, receipt…).
    checksarrayWhen 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.

    statusMeaningWhat to do
    readingEVA is reading the receipt (OCR).Poll again.
    analysingThe category checks are running.Poll again.
    doneAnalysis complete: verdict, extracted and checks are present.Read the verdict.
    unreadableThe receipt could not be read (empty, too blurry, illegible).Ask for a better receipt and submit it again.
    not_applicableNo check applies to this analysis.Handle it outside EVA.
    frozenAnalysis is paused on the EVA side, for instance during maintenance.Poll again later: it will resume.
    stalledNo 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.

    FieldTypeDescription
    codestringStable check identifier, for instance duplicate_check. The list of active checks is visible in your EVA workspace.
    labelstringCheck name.
    passedbooleanTrue when the check is compliant.
    severitystringpassed, failed (confirmed anomaly) or manual_review (doubt: an auditor must decide).
    error_codestring | nullAnomaly reason, when the check provides one.
    messagestringExplanation of the anomaly, empty when the check passed.
    warningstringAdditional 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";
      }
    }

    Integration 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"])

    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.

    HTTPCause
    400Missing or invalid field: unknown category, unsupported file, content not matching the declared type, image too large.
    401Missing, invalid or revoked key, or deactivated account.
    403API not enabled for the workspace, or user without audit rights on all expenses.
    404Unknown analysis in this workspace.
    411Request without a Content-Length header.
    413Request larger than 15 MB.
    422Employee excluded from EVA analysis.
    429Rate limit or daily cap reached.
    Invalid field (400)
    HTTP/1.1 400 Bad Request
    
    {
      "errors": {
        "category": ["Unknown category."],
        "employee_last_name": ["This field is required."]
      }
    }
    Key rejected (401)
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer
    
    { "detail": "Invalid or revoked token." }
    Excluded employee (422)
    HTTP/1.1 422 Unprocessable Entity
    
    {
      "errors": {
        "employee_external_id": ["This person is excluded from EVA analysis."]
      }
    }
    Daily cap reached (429)
    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.
    Platform security and compliance

    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