# Outlevo

> Outlevo qualifies B2B accounts against an approved ICP, finds verified contacts and hands accounts to sales as Readiness Cards. Build on it with the REST API, the TypeScript SDK, the MCP server or the React components. No API call can approve, launch or send: people approve in the Outlevo portal.

## Rules for code you generate

- Base URL: https://api.outlevo.com. Auth: `Authorization: Bearer <key>`. Keys: `olv_test_…` (sandbox) and `olv_live_…`.
- Live keys are server-side only. A browser request with a live key is refused (403 LIVE_KEY_BROWSER_ORIGIN). Put the key in a server env var (OUTLEVO_KEY), never in frontend code, never in git.
- Every POST/PUT/PATCH needs an `Idempotency-Key` header (a fresh UUID per operation; reuse it on retries).
- Metered calls quote first: call without `?confirm=true` to get `{ credit_estimate }`, then call again with `?confirm=true`. Slow work returns 202 `{ job_id }`; poll GET /v1/jobs/{id} or subscribe to webhooks.
- Errors: `{ "error": { "code", "message", "fix", "request_id" } }`.
- Test keys act in your sandbox: 100 fake companies on `sbx-001.example` … `sbx-100.example`, fake contacts, five Readiness Cards. No vendors, no credits; jobs finish after ~3 s. Sandbox webhooks are signed with `whsec_sandbox_outlevo_test_only_000000`.

## Quickstart (sandbox)

```bash
export OUTLEVO_KEY=olv_test_...           # create in the portal: Settings → API keys → Test key
curl -s https://api.outlevo.com/v1/companies -H "authorization: Bearer $OUTLEVO_KEY"
# pick an unresearched company (status null), e.g. sbx-002.example, then:
curl -s -X POST "https://api.outlevo.com/v1/companies/$ID/qualify" -H "authorization: Bearer $OUTLEVO_KEY" -H "idempotency-key: $(uuidgen)"
curl -s -X POST "https://api.outlevo.com/v1/companies/$ID/qualify?confirm=true" -H "authorization: Bearer $OUTLEVO_KEY" -H "idempotency-key: $(uuidgen)"
curl -s "https://api.outlevo.com/v1/jobs/$JOB_ID" -H "authorization: Bearer $OUTLEVO_KEY"
```

## TypeScript SDK (server)

```ts
import { Outlevo, verifyWebhook } from '@outlevo/sdk';
const ol = new Outlevo({ apiKey: process.env.OUTLEVO_KEY! });
const { data } = await ol.companies.list();
const quote = await ol.companies.qualify(data[0].id as string);             // { credit_estimate, confirm_required }
const started = await ol.companies.qualify(data[0].id as string, { confirm: true }) as { job_id: string };
const job = await ol.jobs.wait(started.job_id);                              // status: 'succeeded'
await ol.webhookSubscriptions.create({ url: 'https://your.app/api/outlevo-webhook', events: ['company.qualified', 'job.completed'] });
// in your webhook route, with the RAW body:
const event = await verifyWebhook(rawBody, req.headers['outlevo-signature'], process.env.OUTLEVO_WEBHOOK_SECRET!);
```

## Webhooks

- HTTPS only, public addresses only. Header `Outlevo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`; reject if |now − t| > 300 s; dedupe on `Outlevo-Event-Id`.
- Events: job.completed, job.failed, company.qualified, company.disqualified, contact.verified, revenue_action.proposed, revenue_action.blocked, revenue_action.executed, handoff.created, handoff.accepted, handoff.rejected, campaign.status_changed, audience.ready, outcome.recorded, usage.threshold.

## MCP

Remote server (Streamable HTTP): `https://api.outlevo.com/mcp`, header `Authorization: Bearer <key>`.
Tools: get_context, get_icp, list_companies, get_company, list_revenue_actions, get_job, estimate_credits, qualify_company, research_company, discover_contacts, verify_contact, propose_revenue_action. Metered tools return `{ status: "confirmation_required", credit_estimate }` unless called with `confirm: true`.

```json
{ "mcpServers": { "outlevo": { "type": "http", "url": "https://api.outlevo.com/mcp", "headers": { "Authorization": "Bearer ${OUTLEVO_KEY}" } } } }
```

## Components (React, Web Component)

Render through your own server route that holds the key (templates: Next.js, Express, Supabase Edge Functions):

```tsx
import { OutlevoProvider, ReadinessCard } from '@outlevo/components';
<OutlevoProvider fetcher={(path, init) => fetch(`/api/outlevo${path}`, init)}>
  <ReadinessCard handoffId={id} onDecision={(d) => console.log(d)} />
</OutlevoProvider>
```

Theme with CSS variables: --ol-font, --ol-radius, --ol-surface, --ol-text, --ol-muted, --ol-accent, --ol-danger.

## Reference

- OpenAPI 3.1: https://api.outlevo.com/v1/openapi.json
- API reference: https://developers.outlevo.com/api.html
- Status: https://developers.outlevo.com/status.html