Quickstart

From a new account to your first paid call in five minutes.

This walkthrough takes you through the core loop of the outbound.dev API: create a key, check your balance, find someone's work email, and see what the call cost.

New accounts get $1 of free calls on their first organization. After that, calls draw on a prepaid balance you top up from $10 in the console. A lookup that finds nothing costs nothing.

1. Create a key

Sign up and verify your email.
In the console, open API keys and click Create key. Give it a name and the scopes it needs.
Copy the key now: the full value is shown only once, when you create it. Afterwards the console shows a masked form (ob_live_…34hx).

A key is ob_live_ followed by 32 random characters and a checksum. It belongs to the organization, not to the person who made it, so a teammate leaving never breaks an integration.

Treat API keys like passwords. Never commit them to source control, embed them in client-side code, or share them in tickets. If a key leaks, revoke it in the console and create a new one: revocation is immediate.

2. Check your balance

Send the key as a Bearer token in the Authorization header of every request. Checking the balance is free, and any key can do it:

Request

export OUTBOUND_KEY="ob_live_YOUR_KEY"

curl https://api.outbound.dev/v1/wallet \
  -H "Authorization: Bearer $OUTBOUND_KEY"

Response, 200 OK

{ "balanceUsd": 10.00, "currency": "usd" }

If you get a 401, the key is malformed, expired or revoked: see errors and limits.

3. Find a work email

Give a name and the company's domain. The Idempotency-Key header makes the call safe to retry: send the same key again within 24 hours and you get the first response back, with no second charge.

Request

curl https://api.outbound.dev/v1/emails/find \
  -H "Authorization: Bearer $OUTBOUND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ana-ruiz-halden" \
  -d '{"name": "Ana Ruiz", "companyDomain": "haldenfreight.com"}'

Response, 200 OK

{
  "status": "found",
  "email": {
    "value": "ana@haldenfreight.com",
    "status": "valid",
    "type": "work"
  },
  "usdCharged": 0.01,
  "balanceUsd": 9.99
}

A found email costs $0.01. When no email is found, the call costs nothing.

4. See what it cost

Every response that can cost money carries usdCharged, what this call cost, and balanceUsd, what is left. The same charge shows up in the console's Logs and in the Billing ledger as it happens.

Every response also carries an X-Request-Id header. Quote it when you write to us: it lets us find the exact request.

Where to next

API reference: every endpoint, what it does and what it costs.
Errors and limits: the one envelope every failure uses, every status code, and the rate limits.
llms.txt: hand the API to an agent.