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"}'
Endpoints
OpenAPI Spec (JSON)Engagements
/api/v1/engagementsTokenList engagements. Filters: status, scope (all, mine, certifier), overdue=true, cin, externalRef; page and limit (up to 100)
/api/v1/engagementsTokenCreate 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)
/api/v1/engagements/:idTokenEngagement with its assumptions, report record and documents
Financial statements
/api/v1/engagements/:id/uploadTokenUpload a statement file as multipart form field "file": .xlsx, .xls or .pdf, up to 50 MB. Refused (409) once the inputs are locked
/api/v1/engagements/:id/financialsTokenSend 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)
/api/v1/engagements/:id/assumptionsTokenThe assumptions record: headline rates and whether and by whom the inputs were locked
/api/v1/engagements/:id/assumptions/inputsTokenThe source-tagged valuation inputs (every figure with its origin, source and as-of date), whether they are locked, and any open placeholders
/api/v1/engagements/:id/assumptions/inputsTokenSave 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
/api/v1/engagements/:id/assumptions/previewTokenRecompute the valuation on a set of inputs, body { inputs }, without saving. Flagged indicative while placeholders remain
/api/v1/engagements/:id/assumptions/lockHuman onlyLock the inputs, body { inputs }. Refused while any input is an unsourced placeholder or has no citation (422). An API token gets 403 HUMAN_ONLY
/api/v1/engagements/:id/peers/fetchTokenWhich market-data providers are configured on the deployment, and the CSV layout for a pasted export
/api/v1/engagements/:id/peers/fetchTokenCandidate 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
/api/v1/engagements/:id/researchTokenDated 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
/api/v1/engagements/:id/research/packTokenThe stored research pack (404 until one has been prepared)
/api/v1/engagements/:id/research/packTokenPrepare the research pack: sourced facts, drafted context sections and forecast checks. No body
/api/v1/engagements/:id/research/packTokenEdit 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
/api/v1/engagements/:id/agentTokenBrief for an agent: what it can still do, and what is waiting for the valuer
/api/v1/engagements/:id/agentTokenRun 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)
/api/v1/engagements/:id/computeTokenRun the valuation engine on the locked inputs. No body. 409 if Gate 1 is not locked or the conclusion is already approved
/api/v1/engagements/:id/value-conclusionTokenMethod values, per-share values, weights, DLOM, control premium, approval state and any agent proposal
/api/v1/engagements/:id/value-conclusionTokenBody { 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
/api/v1/engagements/:id/approveHuman onlyRecord a gate decision, body { gate, action, notes? }. An API token gets 403
Report and workings
/api/v1/engagements/:id/workbookTokenExcel workbook of workings: every computed line is a live formula over the inputs. 409 until a computation exists
/api/v1/engagements/:id/report/generateTokenGenerate or regenerate the report. 402 without a payment or an entitled plan; 422 with the QA blockers if the checklist fails
/api/v1/engagements/:id/report/statusTokenReport status, version, signature record and the download path once completed
/api/v1/engagements/:id/report/downloadTokenThe report as Word; add ?format=pdf for the PDF rendered from it. 404 until completed, 402 without a payment or an entitled plan
/api/v1/engagements/:id/share-linksTokenList the read-only client links for an engagement
/api/v1/engagements/:id/share-linksHuman onlyCreate a read-only client link, body { scope, recipientLabel?, expiryHours?, emailTo? }, once the conclusion is approved. An API token gets 403 HUMAN_ONLY
/api/v1/engagements/:id/share-links?linkId=TokenRevoke a client link
Firm: webhooks, tokens, payments
/api/v1/firm/webhooksTokenList webhook subscriptions and the available events (a token needs the webhooks:manage scope)
/api/v1/firm/webhooksTokenRegister a subscription, body { url, events }. The signing secret is returned once. Firm admin, or a token with the webhooks:manage scope
/api/v1/firm/webhooks?subscriptionId=TokenDelete a subscription. Firm admin, or a token with the webhooks:manage scope
/api/v1/settings/api-tokensAdmin sessionList the firm’s API tokens (prefix, scopes, last used, revoked)
/api/v1/settings/api-tokensAdmin sessionMint a token, body { name, scopes? }. The full token is returned once. A token cannot mint another token
/api/v1/settings/api-tokens/:tokenIdAdmin sessionRevoke a token
/api/v1/paymentsTokenStart 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
/api/v1/paymentsTokenPayment history for the firm; with ?engagementId=…"e=true, the price quote for one engagement
System
/api/v1/healthPublicHealth 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.
| Act | Signed-in valuer | API token |
|---|---|---|
| Create an engagement, send financials, compute, read, export | Yes | Yes |
| Save draft inputs | Yes | Proposal only: each changed figure stays an unconfirmed placeholder |
| Research section text | Yes, and approve | Proposal only: stored as a draft, not printed; an approval is ignored |
| Gate 2 weights, DLOM and control premium | Yes, and approve | Proposal only (202); not read by the computation or the report |
| Lock the inputs (Gate 1) | Yes | Refused: 403 HUMAN_ONLY |
| Approve a gate, sign the report, share it outside the firm | Yes | Refused: 403 |
| Mint or revoke API tokens | Firm admin only | Refused: 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_CREATEDASSUMPTIONS_LOCKEDCOMPUTATION_COMPLETEREPORT_SIGNEDPAYMENT_CAPTURED