EchoScan API and Integration Guide

Browser Verifier collects and submits signals in the browser. A successful Submit returns an EchoScan server-issued imprint, which your backend uses to retrieve the official Report.

Building an automated evaluator? The Agent API discovery guide covers the product catalog, OpenAPI contract, and Agent Trial flow. Human Workspace users can connect the production MCP Server through OAuth 2.1 without sharing a Secret API Key.

For command-line setup, see CLI Integration.

Follow this checklist from top to bottom. For the first integration, enter one website URL in Console. EchoScan creates the Web App and default server API key together. As you select or scroll through a step, the right panel adds the execution boundary, practical checks, and the expected result for that stage.

1. Add Your Website

Open first website setup in Console. Enter the website where Browser Verifier will run, such as https://shop.example.com. Console extracts the scheme, host, and port, removes the path, query, and fragment, and saves the exact Origin, then creates the Web App and default server API key in one transaction. Copy the publishable env_... Environment ID after creation.

You can start with localhost:3000, 127.0.0.1:8000 or [::1]:3000 before your website is running. Console defaults these loopback addresses to HTTP and other domains to HTTPS; an explicit HTTP(S) scheme is preserved. The preview shows the exact Origin to save. After local integration works, open the website details in Website integrations, choose Add address, and append your deployment address on a new line while keeping the local address. Save the same configuration: its Environment ID and existing server Key stay unchanged. Adding an address does not prove integration; each website must complete a real Submit and your backend must read the Report for that same Imprint.

The existing free plan supports local integration. Actual browser Submit and server requests are metered separately under the current plan rules, with the same rules for local and deployed websites. Local and deployed data remain in the same Workspace.

2. Save The Server API Key

After first website setup succeeds, Console shows the default API key secret once. Save it immediately in your backend secret manager or environment variables. Keep it out of browser code, logs, and source control. You can later create, rotate, or revoke keys independently in API Key management without changing the Web App.

3. Install Browser Verifier

Install the Browser SDK and pass the Environment ID from step 1 to createEchoScan({ environmentId }). Console owns Allowed Origins, so browser code only needs the public Environment ID.

4. Get And Send The Imprint

Call run() when a protected action such as sign-in, registration, or payment occurs. Send the returned imprint to your own server with the business request.

5. Query The Report On Your Backend

Use the secret API key from step 2 to query the canonical Report endpoint by imprint. The official device identity and risk result come from the server Report.

6. Apply Your Business Decision

Read risk.status, risk.reasons, and risk.findings. Combine the result with account, transaction, and business context to allow, challenge, review, or deny the action. Return only the minimum business result to the browser.

Browser code and server routes may share a repository. The security boundary is where code runs: environmentId is publishable, while the API key is server-only.

Integration succeeds when the browser completes a real Submit and your backend retrieves a valid Report for that same imprint. SUSPICIOUS or DECEPTIVE can be successfully retrieved reports. Handle collection or query failure separately from the risk status.

Get And Send The Imprint

Direct mode requires environmentId in the fixed env_<32 lowercase hex> format. Browser Verifier sends it with fingerprint submission and the correlated public-key request. It does not accept a Workspace ID and does not place an API key or authorization secret in the browser.

Install command
npm install @echoscan/browser-verifier@3.0.5
JavaScript
import { createEchoScan } from '@echoscan/browser-verifier'

const sdk = createEchoScan({
  environmentId: 'env_0123456789abcdef0123456789abcdef'
})
const { imprint } = await sdk.run()

Choose npm or CDN integration. For CDN integration, choose exactly one of the independent ESM and UMD blocks below. Your backend implements the example lookup path.

CDN: ESM (choose one)

Request example
<script type="module">
  import { createEchoScan } from 'https://cdn.echoscan.org/v1/echoscan.esm.js'

  const sdk = createEchoScan({
    environmentId: 'env_0123456789abcdef0123456789abcdef'
  })
  try {
    const { imprint } = await sdk.run()
    const response = await fetch('/api/echoscan/report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ imprint })
    })
    if (!response.ok) throw new Error('Report lookup failed')
    // Continue with the minimal business result from your backend.
  } catch {
    // Collection or lookup failed: stop this action; offer a controlled retry.
  } finally {
    sdk.dispose()
  }
</script>

CDN: UMD (choose one)

Request example
<script src="https://cdn.echoscan.org/v1/echoscan.umd.js"></script>
<script>
(async () => {

  const sdk = window.EchoScan.createEchoScan({
    environmentId: 'env_0123456789abcdef0123456789abcdef'
  })
  try {
    const { imprint } = await sdk.run()
    const response = await fetch('/api/echoscan/report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ imprint })
    })
    if (!response.ok) throw new Error('Report lookup failed')
    // Continue with the minimal business result from your backend.
  } catch {
    // Collection or lookup failed: stop this action; offer a controlled retry.
  } finally {
    sdk.dispose()
  }
})()
</script>

run() returns imprint and an optional minimal diagnostic receipt. New imprints use imp_<32 lowercase hex>.

Allowed Origins are exact browser deployment protection, not secret authentication. Register complete http or https origins such as https://staging.example.com:8443 or http://localhost:3000. Matching preserves scheme and port and lowercases the host. Paths, query strings, fragments, user info, wildcards (including *.example.com), bare domains, null, file://, and extension origins are rejected. An empty allowlist or a missing Origin header rejects every public Submit.

Browser Verifier Initialization Input

Parameter Meaning
environmentId Publishable Browser Environment ID. The server resolves it to the trusted Workspace and validates Allowed Origins

Run output. imprint is the server-issued report identifier returned by a successful run(); send it with the protected business action.

Diagnose One Browser Verifier Run

These examples target Browser Verifier 3.0.5. Use the same version in the browser and its installed assets.

getLastRunTrace() and detailed error-class exports from published 2.x are removed in this major. Keep SDK_VERSION, EchoScanError.category and the minimal diagnostic receipt for support. For the direct profile, not_sent means no correlated API request began; unconfirmed means an ID was sent without a matching receipt; received means a durable server receipt was observed for its named API operation. Unconfirmed requests may have no server record. An ID is never authorization to read diagnostics.

Request example
import { createEchoScan, SDK_VERSION, EchoScanError } from '@echoscan/browser-verifier'

const sdk = createEchoScan({ environmentId: 'env_0123456789abcdef0123456789abcdef' })
try {
  const { imprint } = await sdk.run()
  // Send imprint to your server; only the server queries the business Report.
  await fetch('/api/echoscan/report', {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ imprint, sdkVersion: SDK_VERSION })
  })
} catch (error) {
  const category = error instanceof EchoScanError ? error.category : 'integration_failed'
  const support = { sdkVersion: SDK_VERSION, category,
    diagnostic: error instanceof EchoScanError ? error.diagnostic : null }
  // Provide only this safe summary to support. No automatic diagnostic upload.
  void support
} finally {
  sdk.dispose()
}

Support staff can use the minimal diagnostic receipt to correlate recorded requests and formal Reports within their authorized scope. The receipt does not contain a complete browser session, and an unconfirmed request may have no server record.

Keep Imprint in the controlled business flow and the full Report on your server. Do not copy raw errors, fingerprints, IPs, keys, cookies or parameterized URLs. A technical failure is not a risk verdict, and missing information alone does not establish risk.

A failed Submit or failed Report query is a technical failure, not a risk verdict. Keep that action pending or denied under your business rules. Only recoverable technical failures may use bounded retries; do not keep scanning until PASS. A successfully retrieved SUSPICIOUS or DECEPTIVE Report is evaluated data. Choose allow, challenge, review or deny using your own business context. Your application implements any challenge; your backend still owns eligibility, idempotency and duplicate issuance prevention.

Send Imprint To The Server

Send the imprint with the protected business action using the shape that fits your API.

Request example
await fetch('/api/your-action', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...yourActionPayload,
    echoscanImprint: imprint
  })
})
Request example
await fetch('/api/your-action', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-EchoScan-Imprint': imprint
  },
  body: JSON.stringify(yourActionPayload)
})
Request example
await fetch('/api/echoscan/report', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ imprint })
})

/api/echoscan/report above is an example path owned by the integrator, not an EchoScan endpoint.

Minimal Complete Default Integration

Use Node.js 22.22 or a supported 22.x runtime, pnpm, and the npm-published Browser Verifier. The following is a standalone demo project. For an existing project, preserve its configuration and merge only the required code. First add http://localhost:3000 in Console. Set the actual Environment ID in .env.local and the Secret in .env.server; keep both files out of source control.

package.json

Response example
{
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1 --port 3000 --strictPort",
    "server": "node --env-file=.env.server server.mjs"
  },
  "dependencies": {
    "@echoscan/browser-verifier": "3.0.5",
    "ajv": "8.20.0",
    "ajv-formats": "3.0.1"
  },
  "devDependencies": {
    "vite": "7.3.6"
  }
}

index.html

HTML
<button id="verify" type="button">Verify visit</button>
<p id="result" role="status"></p>
<script type="module" src="/main.js"></script>

main.js

Request example
import { createEchoScan } from '@echoscan/browser-verifier'

const sdk = createEchoScan({ environmentId: import.meta.env.VITE_ECHOSCAN_ENVIRONMENT_ID })
const button = document.querySelector('#verify')
const result = document.querySelector('#result')
button.addEventListener('click', async () => {
  button.disabled = true
  result.textContent = 'Checking…'
  try {
    const { imprint } = await sdk.run()
    const response = await fetch('/api/echoscan/report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ imprint })
    })
    if (!response.ok) throw new Error('Report lookup failed')
    const { decision } = await response.json()
    if (!['allow', 'challenge'].includes(decision)) throw new Error('Invalid decision')
    result.textContent = decision === 'allow' ? 'Report retrieved: allow' : 'Report retrieved: additional verification'
  } catch {
    result.textContent = 'Verification unavailable. Retry when ready.'
  } finally {
    button.disabled = false
  }
})
window.addEventListener('pagehide', () => sdk.dispose(), { once: true })

vite.config.js

JavaScript
export default {
  server: { proxy: { '/api/echoscan/report': 'http://127.0.0.1:3001' } }
}

server.mjs

Request example
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import Ajv2020 from 'ajv/dist/2020.js'
import addFormats from 'ajv-formats'

const apiKey = process.env.ECHOSCAN_API_KEY
if (!apiKey) throw new Error('ECHOSCAN_API_KEY is required')
const contract = JSON.parse(await readFile(new URL('./openapi.json', import.meta.url), 'utf8'))
const ajv = new Ajv2020()
addFormats(ajv)
const validateReport = ajv.compile(contract.components.schemas['public.report.schema.json'])

createServer(async (request, response) => {
  const send = (status, body) => {
    response.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
    response.end(JSON.stringify(body))
  }
  if (request.method !== 'POST' || request.url !== '/api/echoscan/report') {
    send(404, { error: 'not_found' })
    return
  }
  let imprint
  try {
    let body = ''
    for await (const chunk of request) {
      body += chunk
      if (Buffer.byteLength(body) > 2048) throw new Error('Request too large')
    }
    imprint = JSON.parse(body).imprint
    if (typeof imprint !== 'string' || !/^imp_[0-9a-f]{32}$/.test(imprint)) throw new Error('Invalid imprint')
  } catch {
    send(400, { error: 'invalid_request' })
    return
  }
  try {
    const upstream = await fetch(`https://api.echoscan.org/api/v1/fingerprint/report/${imprint}`, {
      headers: { 'X-API-Key': apiKey, Accept: 'application/json' },
      signal: AbortSignal.timeout(5000)
    })
    if (!upstream.ok) {
      // HTTP failures never enter the risk decision branch.
      send(503, { error: 'verification_unavailable' })
      return
    }
    const report = await upstream.json()
    if (!validateReport(report) || report.imprint !== imprint) {
      send(503, { error: 'verification_unavailable' })
      return
    }
    if (report.risk.status === 'UNAVAILABLE') {
      send(503, { error: 'verification_unavailable' })
      return
    }
    const decision = report.risk.status === 'PASS' ? 'allow' : 'challenge'
    send(200, { decision })
  } catch {
    send(503, { error: 'verification_unavailable' })
  }
}).listen(3001, '127.0.0.1')

.gitignore

Text
.env.local
.env.server
node_modules/
dist/

.env.local

Text
VITE_ECHOSCAN_ENVIRONMENT_ID=env_0123456789abcdef0123456789abcdef

.env.server

Text
ECHOSCAN_API_KEY=<your_server_secret_key>
Install command
pnpm install
curl --fail --output openapi.json https://echoscan.org/openapi.json
pnpm server
# In a second terminal:
pnpm dev

Open http://localhost:3000 after starting both processes and click Verify visit. After a real browser Submit, the backend queries the same Imprint and validates the result against the downloaded official OpenAPI Report Schema. Success returns only allow or challenge; failure displays unavailable. This example policy does not perform sign-in, payment, or resource delivery. Preserve your own authentication, authorization, and additional verification policy when integrating it. Download openapi.json in the explicit setup step; normal execution does not fetch remote schemas.

Report Integration (Lite and Pro)

Lite and Pro use the same base Report structure. The common query below also applies after an upgrade; read the Secret API Key only in server-executed code.

Query Report

Request example
GET https://api.echoscan.org/api/v1/fingerprint/report/{imprint}
X-API-Key: <your_lite_key>
Accept: application/json

Node.js, Go, Python, and Rust SDKs wrap the same server HTTP API.

SDK Version Scope

The server SDK installation and call examples on this page pin 0.2.4, which uses the current Report, History, and Account Map routes. In 0.2.3, the Pro method-set clients also use these public routes and can be used with an authorized Lite or Pro key. Its Lite clients still call the retired /api/v1/fingerprint/report-lite/{imprint} route and do not work with the current base Report API. If retaining 0.2.3, use the Pro method-set client for these operations, or upgrade to 0.2.4; client names do not determine your plan.

Public package installation, import/build, and synthetic HTTP examples have been checked. This does not establish production integration for every language SDK.

Backend language
SDK install / dependency
npm install @echoscan/echoscan@0.2.4
Server query example
import { createLiteClient } from '@echoscan/echoscan'

const echoscan = createLiteClient({
  apiKey: process.env.ECHOSCAN_API_KEY
})

const report = await echoscan.getReport(imprint)
console.log(report.risk.status)

Request metering. Browser Submit is recorded for its Browser Environment. Applicable metered API Key and MCP requests share the Workspace server allowance. Metered server routes include Report GET, Account Map POST, History GET, and other applicable protected API calls. A call reaching usage tracking counts once, including an application error or a repeated query of the same Imprint. Requests rejected before tracking by authentication, rate limits, or quota checks do not enter that server count. Browser retries recognized as duplicates by the same submission ID do not consume another Submit unit.

Lite uses a UTC calendar month. Pro Beta and paid Pro use their active entitlement or subscription period. Creating another key does not add quota. Browser Submit and server calls are separate counts, not unique visitor counts. Check Console for the current limits and period.

Canonical Report

Lite and Pro use the same base Report structure; Enterprise keys also use this canonical contract. Optional fields can be omitted when signals or applicable data are unavailable.

Report content What you can learn
Identifier and time Which detection this Report belongs to, and when it was generated.
Device continuity Workspace-scoped Device ID, seen-before state, total visits, and available first and previous seen times.
Current-visit risk Overall risk status, product reasons, and the severity of each finding.
Browser and operating system Identified names, available versions, and their risk statuses.
Network Available egress IP, country or region, proxy results, network consistency, and other context.
Recent activity When available, event, distinct IP, and distinct country counts for 5 minutes, 1 hour, and 24 hours.

A first device record has null for the previous seen time. Preserve the meanings of 0, false, empty collections, and null; handle missing fields according to the public contract. The base continuity summary and recent activity are separate from a History API query for a specified time range.

Normal example:

Response example
{
  "schema_version": "1.0",
  "imprint": "imp_0123456789abcdef0123456789abcdef",
  "created_at": "2026-07-28T01:30:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": false,
    "access_count": 1,
    "previous_seen_at": null
  },
  "risk": {
    "status": "PASS",
    "reasons": [],
    "findings": []
  },
  "browser": {
    "status": "PASS",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "PASS",
    "observed_ip": "203.0.113.10",
    "country_code": "JP",
    "ip_consistency": "MATCH",
    "proxy_detected": false
  },
  "activity": {
    "5m": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "24h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    }
  }
}

Suspicious example:

Response example
{
  "schema_version": "1.0",
  "imprint": "imp_11111111111111111111111111111111",
  "created_at": "2026-07-28T01:35:00Z",
  "device": {
    "id": "did_C98D76E54F32",
    "seen_before": false,
    "access_count": 1,
    "previous_seen_at": null
  },
  "risk": {
    "status": "SUSPICIOUS",
    "reasons": [
      "SIGNAL_DATA_INCOMPLETE"
    ],
    "findings": [
      {
        "reason": "SIGNAL_DATA_INCOMPLETE",
        "status": "SUSPICIOUS"
      }
    ]
  },
  "browser": {
    "status": "SUSPICIOUS",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "PASS",
    "observed_ip": "198.51.100.20",
    "country_code": "US",
    "ip_consistency": "MATCH",
    "proxy_detected": false
  },
  "activity": {
    "5m": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "24h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    }
  }
}

Returning-device example:

Response example
{
  "schema_version": "1.0",
  "imprint": "imp_22222222222222222222222222222222",
  "created_at": "2026-07-28T02:00:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": true,
    "access_count": 8,
    "first_seen_at": "2026-06-10T03:20:00Z",
    "previous_seen_at": "2026-07-27T08:40:00Z"
  },
  "risk": {
    "status": "PASS",
    "reasons": [],
    "findings": []
  },
  "browser": {
    "status": "PASS",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "PASS",
    "observed_ip": "203.0.113.10",
    "country_code": "JP",
    "ip_consistency": "MATCH",
    "proxy_detected": false
  },
  "activity": {
    "5m": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 2,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "24h": {
      "events": 8,
      "distinct_ips": 2,
      "distinct_countries": 1
    }
  }
}

Field Reference

Field Availability Meaning
schema_version Always returned. Public data-structure version used by this report.
imprint Always returned. Unique identifier for this detection report.
created_at Always returned in UTC. Time this report was generated.
device Always returned. Identification result and visit history for this device in the current Workspace.
device.id Always returned. Device ID within the current Workspace.
device.seen_before Always returned. Whether this device was seen before the current visit.
device.access_count Always returned and includes the current visit. Total visits for this device in the current Workspace, including this visit.
risk Always returned. Overall risk result for this visit.
risk.status Always returned. Overall risk level for this visit.
browser Always returned. Browser information identified by EchoScan and its risk status.
browser.status Always returned. Risk level for the browser identity dimension of this visit.
browser.name Returned when available. Browser name identified by EchoScan.
browser.version Returned when available. Browser version identified by EchoScan.
operating_system Always returned. Operating-system information identified by EchoScan and its risk status.
operating_system.status Always returned. Risk level for the operating-system environment dimension of this visit.
operating_system.name Returned when available. Operating-system name identified by EchoScan.
operating_system.version Returned when available. Operating-system version identified by EchoScan.
network Always returned. Network information and risk status for this visit.
network.status Always returned. Risk level for the network dimension of this visit.
network.observed_ip Returned when available. Public egress IP used when this request reached EchoScan.
network.country_code Returned when available. Country or region code associated with the request egress IP.

Finite Values

Field Value Title Meaning Example customer action
device.seen_before true Previously seen EchoScan had seen this device before the current visit.
device.seen_before false First record This visit is the first record for the device.
risk.status PASS No risk currently needs attention Continue processing this visit under the normal business rules. Continue the existing business flow.
risk.status SUSPICIOUS Risk needs attention Evaluate the result together with the account and business context. Add verification, rate limits, or manual review.
risk.status DECEPTIVE Clear high-risk indicators are present The visit shows clear signs of disguise, automation, or a high-risk network. Apply stricter verification, restrictions, or manual review.
risk.status UNAVAILABLE Assessment unavailable Critical data is insufficient to complete the assessment. Show verification unavailable; keep the action pending or deny it according to your business policy.
browser.status PASS Browser information looks normal No browser-information issue currently needs attention.
browser.status SUSPICIOUS Browser information needs attention The browser information contains an issue that needs attention.
browser.status DECEPTIVE Browser information is high risk The browser information shows clear signs of disguise.
operating_system.status PASS Operating-system information looks normal No operating-system information issue currently needs attention.
operating_system.status SUSPICIOUS Operating-system information needs attention The operating-system information contains an issue that needs attention.
operating_system.status DECEPTIVE Operating-system information is high risk The operating-system information shows clear signs of disguise.
network.status PASS Network information looks normal No network-information issue currently needs attention.
network.status SUSPICIOUS Network information needs attention The network information contains a risk that needs attention.
network.status DECEPTIVE Network information is high risk The network information shows clear high-risk indicators.

History and Account Map (Lite / Pro)

Lite and Pro both support History and optional Account Map, including new links and existing snapshot reads. Both use the same server-issued Imprint, server-only Secret boundary, endpoint, and base Report. Pro provides higher request allowances, rate limits, and Browser Environment capacity.

Query Report

The base Report query is shown once in Report Integration. The SDK examples below also demonstrate the separate History operation.

History queries are available in Lite and Pro. The SDK Lite/Pro names describe method sets, not separate Report structures or plan requirements. Use a client exposing the required methods with your active Workspace key:

Request example
GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?days=7&recent=20
X-API-Key: <your_server_key>
Accept: application/json
Request example
GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?from=2026-03-01&to=2026-03-18&recent=20
X-API-Key: <your_server_key>
Accept: application/json
Backend language
SDK install / dependency
npm install @echoscan/echoscan@0.2.4
Server query example
import { createProClient } from '@echoscan/echoscan'

const echoscan = createProClient({
  apiKey: process.env.ECHOSCAN_API_KEY
})

const report = await echoscan.getReport(imprint)
console.log(report.risk.status, report.risk.reasons)
const history = await echoscan.getHistory(imprint, { days: 7 })

Optional: Enable Account Map (Lite / Pro)

Use Account Map when you need to answer questions such as:

  • How many accounts are associated with this device?
  • How many devices has this account used?
  • Have this account and device appeared together before?
  • Is one device receiving many new account relationships in a short period?
  • Could the pattern indicate account sharing or account takeover?

Lite and Pro both support creating Account Map links. Pass the stable internal user ID with the server-side Report query.

Node.js

Request example
const report = await pro.getReport(imprint, {
  accountRef: currentUser.id
})

Go

Request example
report, err := pro.GetReportWithOptions(
	context.Background(),
	imprint,
	echoscan.ReportOptions{AccountRef: currentUser.ID},
)
if err != nil {
	return err
}

Python

Request example
report = pro.get_report(
    imprint,
    account_ref=current_user.id,
)

Rust

Request example
use echoscan::ReportOptions;

let report = pro
    .get_report_with_options(
        imprint,
        ReportOptions { account_ref: Some(current_user.id.clone()) },
    )
    .await?;

Account Map is completely optional. Use a stable, non-sensitive, immutable internal user primary key as accountRef. Do not send an email address, phone number, real name, nickname, or mutable username. Account relationships are isolated by Workspace.

A Report GET can return an existing snapshot for that Imprint without a new accountRef. Creating an Account Map link and reading an existing snapshot are separate operations. Returning to Lite does not by itself make an existing snapshot disappear. Account Map v1 does not automatically change risk.status; interpret relationship signals with your own business rules.

Consistency for concurrent or delayed linking

Account Map statistics include only relationships that have completed and are visible when the response is generated.

Concurrent POST responses cannot anticipate other relationships that have not completed yet.

After all concurrent or delayed links complete, later GET responses recompute historical statistics in server event order (recorded_at, then event_id).

An earlier event keeps its historical boundary, while a later event includes visible relationships at or before its boundary.

Account Map response example:

Response example
{
  "account_map": {
    "account_seen_before": true,
    "relationship_seen_before": false,
    "accounts_on_device": 7,
    "devices_on_account": 2,
    "accounts_first_seen_on_device_1h": 4
  }
}
Field Meaning
account_seen_before Whether this account appeared on any device in the current Workspace before this visit.
relationship_seen_before Whether this exact account and current device appeared together before this visit.
accounts_on_device Number of distinct accounts associated with the current device, including the current relationship.
devices_on_account Number of distinct devices associated with the current account, including the current relationship.
accounts_first_seen_on_device_1h Number of accounts whose first relationship with the current device occurred during the previous hour. When accountRef is sent after registration, this can approximate new registrations. When sent only at sign-in, it counts accounts first observed by EchoScan and does not prove that the account was just created.

Report Fields And Reasons

The canonical Report always uses this field model. Optional values follow the public contract and available signals or applicable data. account_map can contain an existing snapshot; it is not guaranteed on every request.

Response example
{
  "schema_version": "1.0",
  "imprint": "imp_0123456789abcdef0123456789abcdef",
  "created_at": "2026-07-28T01:30:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": true,
    "access_count": 42,
    "first_seen_at": "2026-06-10T03:20:00Z",
    "previous_seen_at": "2026-07-27T08:40:00Z"
  },
  "risk": {
    "status": "DECEPTIVE",
    "reasons": [
      "BROWSER_VERSION_MISMATCH",
      "PROXY_DETECTED",
      "NETWORK_INCONSISTENT"
    ],
    "findings": [
      {
        "reason": "BROWSER_VERSION_MISMATCH",
        "status": "DECEPTIVE"
      },
      {
        "reason": "PROXY_DETECTED",
        "status": "DECEPTIVE"
      },
      {
        "reason": "NETWORK_INCONSISTENT",
        "status": "DECEPTIVE"
      }
    ]
  },
  "browser": {
    "status": "DECEPTIVE",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "DECEPTIVE",
    "observed_ip": "198.23.233.104",
    "country_code": "US",
    "alternate_ip": "126.234.173.23",
    "ip_consistency": "MISMATCH",
    "proxy_detected": true,
    "location": {
      "country_name": "United States",
      "region": "Illinois",
      "city": "Elk Grove Village",
      "timezone": "America/Chicago"
    },
    "provider": "Example Hosting Provider",
    "connection_type": "proxy",
    "asn": 36352
  },
  "activity": {
    "5m": {
      "events": 2,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 8,
      "distinct_ips": 2,
      "distinct_countries": 2
    },
    "24h": {
      "events": 21,
      "distinct_ips": 4,
      "distinct_countries": 3
    }
  }
}

A passing report still serializes explicit empty reasons and findings arrays:

Response example
{
  "risk": {
    "status": "PASS",
    "reasons": [],
    "findings": []
  }
}

The tables below provide the return rule for every field and the product meaning of each finite machine value.

Product Reasons

Reason Meaning
BROWSER_VERSION_MISMATCH Browser version information is inconsistent
OS_ENVIRONMENT_MISMATCH Operating-system environment information is inconsistent
AUTOMATION_DETECTED Automated access was detected
ENVIRONMENT_INCONSISTENT Current device environment information is inconsistent
PROXY_DETECTED Proxy or VPN risk was detected
HOSTING_NETWORK_DETECTED Access originated from a hosting service or datacenter network
NETWORK_INCONSISTENT Network identity information is inconsistent
LOCATION_INCONSISTENT Location-related information is inconsistent
SIGNAL_DATA_INCOMPLETE Critical data for this detection is incomplete

A reason names the risk category. Overall severity is expressed by risk.status; each risk.findings entry also carries the severity contributed by that reason.

Canonical Additional Fields

Field Availability Meaning
device.first_seen_at Returned when available, in UTC. Time this Workspace first saw the device.
device.previous_seen_at Always returned; null on the first visit. Most recent time this device was seen before the current visit.
risk.reasons Always returned. Returns an empty array [] for PASS. Product-level reason categories associated with this risk result.
risk.findings Always returned. Returns an empty array [] for PASS. Reason and severity pairs used to produce the report verdict.
network.alternate_ip Returned when available. Client public IP detected by EchoScan.
network.ip_consistency Always returned. Consistency result between the client public IP and request egress IP.
network.proxy_detected Returned when available. Whether proxy or VPN risk was detected.
network.location Returned when available. Network location information associated with the request egress IP.
network.location.country_name Returned when available with network.location. Country or region name associated with the request egress IP.
network.location.region Returned when available with network.location. Region or first-level administrative area associated with the request egress IP.
network.location.city Returned when available with network.location. City associated with the request egress IP.
network.location.timezone Returned when available with network.location. Time zone associated with the network location of the request egress IP.
network.provider Returned when available. Network organization or service provider associated with the request egress IP.
network.connection_type Returned when available. Network type associated with the request egress IP.
network.asn Returned when available. Autonomous system number associated with the request egress IP.
activity Returned when available. Summary of recent visit activity for the current device.
activity.5m Always returned with activity and includes this visit. Visit activity for the current device during the last 5 minutes.
activity.5m.events Always returned with its time window. Number of visits in this time window.
activity.5m.distinct_ips Always returned with its time window. Number of distinct IP addresses in this time window.
activity.5m.distinct_countries Always returned with its time window. Number of distinct countries or regions in this time window.
activity.1h Always returned with activity and includes this visit. Visit activity for the current device during the last hour.
activity.1h.events Always returned with its time window. Number of visits in this time window.
activity.1h.distinct_ips Always returned with its time window. Number of distinct IP addresses in this time window.
activity.1h.distinct_countries Always returned with its time window. Number of distinct countries or regions in this time window.
activity.24h Always returned with activity and includes this visit. Visit activity for the current device during the last 24 hours.
activity.24h.events Always returned with its time window. Number of visits in this time window.
activity.24h.distinct_ips Always returned with its time window. Number of distinct IP addresses in this time window.
activity.24h.distinct_countries Always returned with its time window. Number of distinct countries or regions in this time window.
account_map Optional; returned when an existing snapshot is available or a link operation returns one. Workspace-isolated account-relationship snapshot for this Imprint.

Network Finite Values

Field Value Title Meaning Example customer action
network.ip_consistency MATCH IP information matches Network IP information is consistent.
network.ip_consistency MISMATCH IP information differs Network IP information is inconsistent.
network.ip_consistency UNKNOWN No clear result No clear IP consistency result is available.
network.proxy_detected true Risk detected Proxy or VPN risk was detected.
network.proxy_detected false No risk detected No proxy or VPN risk was detected.
network.connection_type residential Residential Residential broadband network.
network.connection_type mobile Mobile Mobile carrier network.
network.connection_type corporate Corporate Business or institutional network.
network.connection_type hosting Hosting Cloud, server-hosting, or datacenter network.
network.connection_type proxy Proxy Proxy, VPN, or similar relay network.
network.connection_type unknown Unclassified The network has not been assigned a specific type.

History

History queries a specified time range and is available in both Lite and Pro, separate from the base Report continuity summary.

Response example
{
  "imprint": "imp_33333333333333333333333333333333",
  "range": {
    "from": "2026-03-01",
    "to": "2026-03-18",
    "days": 18
  },
  "summary": {
    "events": 12,
    "truncated": false,
    "firstSeenAt": "2026-03-01T08:10:00+09:00",
    "lastSeenAt": "2026-03-18T21:34:00+09:00"
  },
  "timeline": [
    {
      "date": "2026-03-01",
      "count": 2
    },
    {
      "date": "2026-03-18",
      "count": 3
    }
  ],
  "recent": [
    {
      "at": "2026-03-18T21:34:00+09:00",
      "surface": "login"
    }
  ]
}

days is mutually exclusive with from/to; from and to must be provided together in YYYY-MM-DD format.

History Field Reference

Field Meaning
imprint Detection report identifier used for this History query
range Time range applied to this History query
range.from First date in the query range
range.to Last date in the query range
range.days Number of calendar days covered by the range
summary Aggregate summary for the selected range
summary.events Total visit events in the selected range
summary.truncated Whether the response reached its return limit
summary.firstSeenAt Earliest event time inside the selected range
summary.lastSeenAt Most recent event time inside the selected range
timeline Daily visit-count series
timeline.date Calendar date for a timeline entry
timeline.count Visit events recorded on that date
recent Most recent visit-event list
recent.at Time of a recent event
recent.surface Customer-provided business surface identifier

Live Data Deletion

Delete current live detection data by Workspace, Browser Environment, device, or account. Processing is asynchronous; query the request receipt for its status.

Call from server-side code with an active Workspace Server API Key in X-API-Key. Every ordinary server key for that Workspace has deletion capability. Browser Environment IDs, Console cookies, Agent Trial credentials, and MCP authorization do not apply. The key determines the Workspace; the body does not accept workspace_id. This operation is available through HTTP only; server SDKs and Console do not yet expose a deletion operation.

Choose A Deletion Scope

scope Selectors Deletion scope
workspace No additional selectors All detection history and associated data in the current Workspace, including anonymous visits, Account Map links, and visits with no recorded environment.
environment Required environment_id All detection history and associated data for the specified Browser Environment, including anonymous visits, regardless of the date range displayed in Console.
device Required device_id; optional environment_id The device’s visits and associated data within the selected scope, including visits made under any account on that device.
account Required account_ref; optional environment_id Visits explicitly bound to the Account Map reference and their associated data. A matching device or IP does not expand selection to unbound visits.

Use the env_... from Console website integration as environment_id; disabled environments can also be cleaned. Use the Report’s device.id as device_id. For account_ref, use the same stable internal user ID supplied when binding the Report. Omitting environment_id from device or account requests selects matching history across the Workspace.

Deletion includes detection records and Account Map links directly associated with the selected visits, plus device data whose ownership can be confirmed. Other Workspaces remain unchanged. Shared device data or uncertain ownership puts the entire request into review_required; no partial deletion occurs.

Submit A Deletion Request

POST /api/v1/data-deletions returns HTTP 202 and a request receipt. HTTP 202 confirms acceptance; completion is determined by the receipt’s status.

Browser Environment scope:

Request example
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "scope": "environment",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "confirmation": "DELETE_LIVE_DATA"
}
Field Rule
request_id Required. Generate a random 32-character lowercase hexadecimal ID for each new operation and persist it before sending. Reuse it on retries. Example IDs are not for actual requests.
scope Required. workspace, environment, device, or account.
confirmation Required. Must be DELETE_LIVE_DATA.
environment_id Required for environment, optional for device and account, and omitted for workspace.
device_id Only for device. Never combine it with account_ref.
account_ref Only for account. At most 256 bytes, without control characters or surrounding whitespace.

The body is limited to 4096 bytes. Omit inapplicable fields; null, duplicate fields, and undeclared fields are rejected.

Workspace scope:

Request example
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "scope": "workspace",
  "confirmation": "DELETE_LIVE_DATA"
}

Device scope, limited to a Browser Environment:

Request example
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "scope": "device",
  "device_id": "did_example_device_1",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "confirmation": "DELETE_LIVE_DATA"
}

Account scope, limited to a Browser Environment:

Request example
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "cccccccccccccccccccccccccccccccc",
  "scope": "account",
  "account_ref": "EXAMPLE-customer-42",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "confirmation": "DELETE_LIVE_DATA"
}

Acceptance receipt:

Response example
{
  "request_id": "0123456789abcdef0123456789abcdef",
  "scope": "environment",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "status": "queued",
  "received_at": "2026-11-05T00:00:00Z",
  "copies_status": "not_verified"
}

Query The Result

GET /api/v1/data-deletions/{requestId} returns HTTP 200 and the current receipt. Use a currently active Server API Key for the same Workspace. The path’s requestId is the request_id saved before submission.

Request example
GET https://api.echoscan.org/api/v1/data-deletions/0123456789abcdef0123456789abcdef
X-API-Key: <your_server_key>
Accept: application/json

HTTP 200 confirms receipt retrieval; status determines the deletion outcome. Poll every few seconds with a timeout, retaining the original request ID for subsequent queries or support review.

Completion receipt:

Response example
{
  "request_id": "0123456789abcdef0123456789abcdef",
  "scope": "environment",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "status": "live_data_deleted",
  "received_at": "2026-11-05T00:00:00Z",
  "finished_at": "2026-11-05T00:00:01Z",
  "copies_status": "not_verified",
  "deleted": {
    "visit_events": 12,
    "devices": 3
  }
}

Deletion Receipt Fields

Field Meaning
request_id Deletion request ID.
scope Requested deletion scope.
environment_id Returned when the request specifies a Browser Environment.
status Current processing status.
received_at Request receipt time.
finished_at Processing end time; optional.
copies_status Always not_verified; copy erasure is not verified by this API.
reason Review or execution failure reason code.
deleted Successful deletion counts by data category. An absent target can produce zero counts; category counts are not visitor counts.

Status And Review

status Meaning and action
queued Accepted or executing; keep querying.
live_data_deleted Current live detection data in the selected scope has been deleted.
review_required No deletion occurred. Contact support with the request ID and reason.
failed Deletion did not commit and processing has ended. Reconcile the cause before deciding whether to create a new request.

Review reasons are shared_device_data (shared device data), account_key_version_review (Account Map relationships need review), and ownership_review (data ownership needs review). Execution failures use execution_failed. Both review_required and failed are terminal and do not automatically retry.

Retries And Errors

Repeating POST with the same request_id and target returns the original receipt without executing deletion again. Changing the scope or selectors returns a conflict. GET retrieves the original receipt without resubmitting the target.

HTTP / error.code Action
400 / invalid_deletion_request Check the scope, fields, and confirmation.
401 / invalid_api_key Check that the server key is valid.
403 / data_deletion_forbidden Use an ordinary server key for the Workspace.
404 / data_deletion_environment_not_found Check that the environment belongs to the key’s Workspace.
404 / data_deletion_not_found No receipt was found in the current Workspace; this does not confirm deletion.
409 / data_deletion_conflict Check the original ID and target, then GET the original result.
429 / data_deletion_busy Honor Retry-After: 10. Each Workspace allows one queued request, with at least 10 seconds between new requests.
429 / key_rate_limited Reduce request and polling frequency.
500 / data_deletion_failed The result is uncertain; retry the original ID and selectors.
503 / data_deletion_unavailable Temporarily unavailable; retain the original request ID.

Reuse the original ID after a lost response. If POST repeatedly returns 503 while GET returns 404, stop automatic retries and contact support with that ID. Do not use a new ID to bypass an uncertain result. Submission and polling do not consume detection/Report quota; ordinary request rate limits still apply.

Retention Boundaries

The Workspace, login accounts, members, Browser Environment configuration, API keys, installations, OAuth grants, billing, and actual usage remain unchanged. Account closure and a complete integration Reset are separate operations.

live_data_deleted confirms current live detection data only. Backups, exports, logs, and research copies are outside this confirmation, and copies_status remains not_verified. Deletion requests involving copies require separate handling through support; this status does not authorize continued use of those copies.

Deletion does not prevent future collection. Pause collection before clearing a test batch, wait for live_data_deleted, then start the next batch with fresh SDK submission IDs. Disable the corresponding Browser Environment or stop integration calls when future collection must also stop.

Server Decision

Use risk.status, risk.reasons, and risk.findings as report inputs and combine them with account, transaction, and business context. Network details and activity are part of the canonical Report; History is a separate time-range operation available in both plans.

JavaScript
if (report.risk.status === 'UNAVAILABLE') {
  return Response.json({ error: 'verification_unavailable' }, { status: 503 })
}

const decision =
  report.risk.status === 'PASS'
    ? 'allow'
    : 'challenge'

return Response.json({ decision })

This allow-or-challenge branch is an example customer policy. EchoScan Report API v1 does not return recommended_action.

Keep the full report server-side and return only the business result needed by the browser.

Error Shape

Response example
{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid"
  }
}

Branch on error.code; treat error.message as display text.

Error Field Reference

Field Meaning
error Public error object
error.code Stable machine code for server-side branching
error.message Error description suitable for logs or interface text

Failure Stages And Recovery

SDK 3.0 uses EchoScanError.category, with SDK version and a minimal correlation receipt. Do not parse messages or import the old detailed Error/Transport classes.

Category Meaning and recovery
configuration, run_in_progress, disposed Fix the options/lifecycle; this rejected call has no new API receipt.
detection_failed Collection did not produce a submittable result. Keep the business action pending or denied.
cancelled, timeout The server may have received a request. Check the receipt state; failure is not PASS.
submission_failed Delivery, API response or validation failed. Give support the safe receipt and category; do not fabricate a Report.

Public-key GET can retry transient failures; Browser Verifier does not automatically retry Submit POST. A new run() is a new collection/submission, not a guaranteed replay with the previous submission ID. Recognized same-ID duplicate submissions do not consume Submit quota twice, but a fresh run may consume new usage.

For direct HTTP, check the status before reading the success contract. Branch on error.code from the envelope; do not assume every proxy/network failure has JSON. invalid_api_key, origin_not_allowed, quota_exceeded, and key_rate_limited require the corresponding credential, Origin, quota, or backoff correction. A successful HTTP response still needs Report validation and the same Imprint.

HTTP 503 quota_state_unavailable. The service cannot reliably read or settle the current quota usage state and stops before executing the protected operation. This is a temporary availability failure, distinct from HTTP 429 quota_exceeded; it does not establish that your allowance is exhausted. Display verification unavailable, never PASS. Retry GET only within your configured limits after service recovery; avoid continuous polling. Changing keys or upgrading a plan does not repair unavailable quota state. If the failure persists, retain the HTTP status, public error code, and request identifier for support without logging keys or the full Report. For a write with an uncertain response, check the existing snapshot before deciding whether to repeat it.

Server SDK errors are normalized separately in 0.2.3 and 0.2.4: Node EchoScanApiError.code / serverCode; Go APIError.Code / ServerCode; Python ApiError.code / server_code; Rust ApiError.code / server_code. For this 503, the normalized code is upstream_unavailable and the server-code field retains quota_state_unavailable. The HTTP status, request identifier, and retry fields use each language’s public types. Check the matching public SDK types for your installed version.

Server SDK GET wrappers can retry transient failures according to their configured limits. Each tracked retry or repeated Report GET can consume server usage, even after a business error. Authentication/rate/quota refusals before tracking do not consume that count. Account Map POST is a write: do not blindly retry it or change the account reference after an uncertain response. These failures must never fall through to the PASS branch.

Connect AI With EchoScan MCP

Use standard MCP to connect Codex, Claude Code, VS Code, or another compatible client directly to EchoScan. The client opens browser authorization the first time it needs access to a Workspace.

REMOTE MCP SERVER

Connect EchoScan to your AI

Add this remote endpoint once. Your client opens EchoScan authorization when access is required—no API key is pasted into the AI client.

Streamable HTTP OAuth 2.1 + PKCE
Server endpoint https://api.echoscan.org/mcp
View setup methods
Choose your client

Run this once in a terminal, then approve the EchoScan workspace and permissions in your browser.

Codex
codex mcp add echoscan --url https://api.echoscan.org/mcp

Primary tools (summary) are echoscan_get_report, echoscan_get_history, and echoscan_get_usage. See the MCP guide for the complete tool and OAuth scope list, enablement conditions, and call permissions. This summary is not the full tool list.

If the AI will also change EchoScan integration code, give it these canonical sources first:

  • https://echoscan.org/llms.txt
  • https://echoscan.org/docs/ai-context.md

They are maintained against the same public API contract and validated for consistency. MCP authorization never requires you to paste an EchoScan API key into the AI client.

CLI Integration

Create EchoScan integration configuration and check connection status. Requires Node.js 22.22 or a later 22.x release. Run in your project directory:

Install command
npx @echoscan/cli init --origin https://example.com

Authorize EchoScan CLI in your browser and select a Workspace. After creating configuration, follow the recommended flow to connect Browser Verifier and your backend, then check the connection:

Install command
npx @echoscan/cli status
npx @echoscan/cli verify

status shows the current connection state. verify succeeds when both the browser and server are connected. The CLI creates configuration; it does not install SDKs or modify application code.

npm package and README