Skip to main content
API Reference

Build with Evaaluate.

A REST API for creating valuations, sending financial statements, proposing inputs and downloading reports. Confirming, approving, locking and signing are reserved to a signed-in professional.

Quickstart

1. Authenticate

A firm admin mints an API token with POST /api/v1/settings/api-tokens while signed in to Evaaluate. There is no token screen in the app yet. Send the token as a Bearer token on every request.

2. Create Engagement

POST to /api/v1/engagements with the company, the purpose and the valuation date. Then send the financial statements: a file to /upload or JSON to /financials.

3. Hand Over, Then Download

Propose inputs or run the assistant and read its brief. A valuer confirms and locks the inputs, approves the conclusion and signs. Poll the report status, then download the report in Word or PDF.

# Create a valuation engagement

curl -X POST https://evaaluate.com/api/v1/engagements \

-H "Authorization: Bearer evk_YOUR_TOKEN" \

-H "Content-Type: application/json" \

-d '{"targetEntity":"Acme Pvt Ltd","statute":"FEMA_RBI","engagementPurpose":"FDI_INBOUND","valuationDate":"2026-09-30"}'

Engagements

GET/api/v1/engagementsToken

List engagements. Filters: status, scope (all, mine, certifier), overdue=true, cin, externalRef; page and limit (up to 100)

POST/api/v1/engagementsToken

Create an engagement: targetEntity and statute are required; engagementPurpose and valuationDate select the catalogue entry. Optional externalRef makes it idempotent (same payload: 200 deduped; different payload: 409); optional capitalEvent carries share-issue facts. A method the purpose does not permit is refused (422)

GET/api/v1/engagements/:idToken

Engagement with its assumptions, report record and documents

Financial statements

POST/api/v1/engagements/:id/uploadToken

Upload a statement file as multipart form field "file": .xlsx, .xls or .pdf, up to 50 MB. Refused (409) once the inputs are locked

POST/api/v1/engagements/:id/financialsToken

Send statements as JSON in rupees: years, profitAndLoss (revenue required), balanceSheet, optional cashFlow; one value per year, up to 2 MB. Refused (409) once the inputs are locked

Inputs (Gate 1)

GET/api/v1/engagements/:id/assumptionsToken

The assumptions record: headline rates and whether and by whom the inputs were locked

GET/api/v1/engagements/:id/assumptions/inputsToken

The source-tagged valuation inputs (every figure with its origin, source and as-of date), whether they are locked, and any open placeholders

PUT/api/v1/engagements/:id/assumptions/inputsToken

Save a draft of the inputs, body { inputs }. Each save is a revision with a field-level diff. With an API token every changed figure is stored as an unconfirmed proposal

POST/api/v1/engagements/:id/assumptions/previewToken

Recompute the valuation on a set of inputs, body { inputs }, without saving. Flagged indicative while placeholders remain

POST/api/v1/engagements/:id/assumptions/lockHuman only

Lock the inputs, body { inputs }. Refused while any input is an unsourced placeholder or has no citation (422). An API token gets 403 HUMAN_ONLY

GET/api/v1/engagements/:id/peers/fetchToken

Which market-data providers are configured on the deployment, and the CSV layout for a pasted export

POST/api/v1/engagements/:id/peers/fetchToken

Candidate listed peers as at the valuation date: { provider: "fmp" | "eodhd", symbols } or { provider: "csv", csv }. Nothing is saved; the valuer imports and chooses

Research and assistant

GET/api/v1/engagements/:id/researchToken

Dated market snapshot for the valuation date and industry (?industry= to preview another Damodaran industry). The risk-free rate is not included: the valuer enters it

GET/api/v1/engagements/:id/research/packToken

The stored research pack (404 until one has been prepared)

POST/api/v1/engagements/:id/research/packToken

Prepare the research pack: sourced facts, drafted context sections and forecast checks. No body

PATCH/api/v1/engagements/:id/research/packToken

Edit section text and, for a signed-in valuer, approve it, body { sections: [{ id, text?, status? }] }. With an API token the text is stored as a draft proposal and an approval is ignored

GET/api/v1/engagements/:id/agentToken

Brief for an agent: what it can still do, and what is waiting for the valuer

POST/api/v1/engagements/:id/agentToken

Run one assistant pass: gather data, draft research, propose a peer screen, a forecast repair and Gate 2 weights, and recompute the indicative value. It never confirms, approves, locks or signs

Computation and value conclusion (Gate 2)

POST/api/v1/engagements/:id/computeToken

Run the valuation engine on the locked inputs. No body. 409 if Gate 1 is not locked or the conclusion is already approved

GET/api/v1/engagements/:id/value-conclusionToken

Method values, per-share values, weights, DLOM, control premium, approval state and any agent proposal

POST/api/v1/engagements/:id/value-conclusionToken

Body { dcfWeight, navWeight, comparableWeight, dlom, controlPremium } as fractions; weights sum to 1. A signed-in valuer or admin approves the conclusion. An API token records a proposal (202) and approves nothing

POST/api/v1/engagements/:id/approveHuman only

Record a gate decision, body { gate, action, notes? }. An API token gets 403

Report and workings

GET/api/v1/engagements/:id/workbookToken

Excel workbook of workings: every computed line is a live formula over the inputs. 409 until a computation exists

POST/api/v1/engagements/:id/report/generateToken

Generate or regenerate the report. 402 without a payment or an entitled plan; 422 with the QA blockers if the checklist fails

GET/api/v1/engagements/:id/report/statusToken

Report status, version, signature record and the download path once completed

GET/api/v1/engagements/:id/report/downloadToken

The report as Word; add ?format=pdf for the PDF rendered from it. 404 until completed, 402 without a payment or an entitled plan

GET/api/v1/engagements/:id/share-linksToken

List the read-only client links for an engagement

POST/api/v1/engagements/:id/share-linksHuman only

Create a read-only client link, body { scope, recipientLabel?, expiryHours?, emailTo? }, once the conclusion is approved. An API token gets 403 HUMAN_ONLY

DELETE/api/v1/engagements/:id/share-links?linkId=Token

Revoke a client link

Firm: webhooks, tokens, payments

GET/api/v1/firm/webhooksToken

List webhook subscriptions and the available events (a token needs the webhooks:manage scope)

POST/api/v1/firm/webhooksToken

Register a subscription, body { url, events }. The signing secret is returned once. Firm admin, or a token with the webhooks:manage scope

DELETE/api/v1/firm/webhooks?subscriptionId=Token

Delete a subscription. Firm admin, or a token with the webhooks:manage scope

GET/api/v1/settings/api-tokensAdmin session

List the firm’s API tokens (prefix, scopes, last used, revoked)

POST/api/v1/settings/api-tokensAdmin session

Mint a token, body { name, scopes? }. The full token is returned once. A token cannot mint another token

DELETE/api/v1/settings/api-tokens/:tokenIdAdmin session

Revoke a token

POST/api/v1/paymentsToken

Start the per-report charge for an engagement, body { engagementId }, through the ORIS billing platform; returns the checkout order, or free: true for a free valuation

GET/api/v1/paymentsToken

Payment history for the firm; with ?engagementId=…&quote=true, the price quote for one engagement

System

GET/api/v1/healthPublic

Health of the application: database, cache, file storage and outbound connectivity. 200 when healthy, 503 when degraded

Authentication

Machine callers authenticate with a firm API token (format evk_…). A firm admin mints one by calling POST /api/v1/settings/api-tokens with a JSON body such as {"name":"Integration"} from their signed-in browser session, and revokes it with DELETE /api/v1/settings/api-tokens/:tokenId. The full token is shown exactly once, only its SHA-256 is stored, and it acts with Valuer privileges scoped to your firm. A token never approves a gate, and has no scopes unless one is requested at mint time (webhooks:manage lets it manage this firm's webhook subscriptions).

Include it in the Authorization header: Authorization: Bearer evk_YOUR_TOKEN. A browser session also works for the same endpoints.

What a token can and cannot do

A machine may prepare, suggest and build; only a signed-in professional may confirm, approve, lock or sign. The rule is enforced on the server. Proposals, and a token's refused attempt to lock the inputs, are written to the audit journal. The software itself never certifies a report: the professional who signs it does.

ActSigned-in valuerAPI token
Create an engagement, send financials, compute, read, exportYesYes
Save draft inputsYesProposal only: each changed figure stays an unconfirmed placeholder
Research section textYes, and approveProposal only: stored as a draft, not printed; an approval is ignored
Gate 2 weights, DLOM and control premiumYes, and approveProposal only (202); not read by the computation or the report
Lock the inputs (Gate 1)YesRefused: 403 HUMAN_ONLY
Approve a gate, sign the report, share it outside the firmYesRefused: 403
Mint or revoke API tokensFirm admin onlyRefused: 403

The product also includes an MCP server (stdio) that wraps these endpoints with tools to read, prepare and propose. It has no tool to confirm, approve, lock or sign.

Webhooks

Receive notifications when an engagement moves on. Firm admins configure webhook URLs in Settings, or with POST /api/v1/firm/webhooks. Each delivery carries X-Webhook-Signature: t=<ts>,v1=<hex>, an HMAC-SHA256 of <ts>.<raw body> keyed with the SHA-256 hex digest of your signing secret.

ENGAGEMENT_CREATED
ASSUMPTIONS_LOCKED
COMPUTATION_COMPLETE
REPORT_SIGNED
PAYMENT_CAPTURED
Get API Access