River API reference

Quick start

export RIVER_BASE=https://river.lupolabs.ai
export RIVER_KEY=rk_live_...            # your API key, from LUPO

curl -s "$RIVER_BASE/v1/lookups" \
  -H "Authorization: Bearer $RIVER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8841" \
  -d '{"email":"someone@example.com","external_id":"user_8841","country":"US"}'

curl -s "$RIVER_BASE/v1/lookups/lkp_3f9c0a1b2c3d4e5f60718293" \
  -H "Authorization: Bearer $RIVER_KEY"

curl -s -X PUT "$RIVER_BASE/v1/webhook" \
  -H "Authorization: Bearer $RIVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.yourcompany.com/river"}'

# send a signed ping now
curl -s -X POST "$RIVER_BASE/v1/webhook/test" -H "Authorization: Bearer $RIVER_KEY"

import express from "express";
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.RIVER_WEBHOOK_SECRET); // "whsec_..."
const app = express();

app.post("/river", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.status(400).end();
  }
  // Deduplicate on req.headers["webhook-id"]. Keep the highest event.sequence per event.data.id.
  res.status(204).end();
});

import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["RIVER_WEBHOOK_SECRET"])  # "whsec_..."
app = Flask(__name__)

@app.post("/river")
def river():
    headers = {k.lower(): v for k, v in request.headers.items()}
    try:
        event = wh.verify(request.get_data(), headers)
    except Exception:
        return "", 400
    # Deduplicate on headers["webhook-id"]. Keep the highest event["sequence"] per event["data"]["id"].
    return "", 204

Authentication

Send your key on every request: Authorization: Bearer rk_live_.... A missing, unknown or revoked key always gets the same 401. Keep keys on your server; never put one in a browser or an app. GET /v1/health is the only path that needs no key.

Endpoints

Paths are exact and have no trailing slash. Any other path gets the JSON 404 not_found.

Responses

GET /v1/lookups returns a page. has_more is false on the last page.

{ "object": "list", "data": [ { "id": "lkp_...", "object": "lookup", "...": "lookup objects, newest first" } ], "has_more": true }

PUT /v1/webhook returns the endpoint. The first registration answers 201 and is the only answer that carries secret, unless you send "rotate_secret": true (then 200 with the new secret). Every other PUT answers 200 without it. GET /v1/webhook returns the same object without secret.

{
  "object": "webhook_endpoint",
  "id": "8d0c6f1e-3b7a-4f5e-9a51-2c1d0e9f7a64",
  "url": "https://hooks.yourcompany.com/river",
  "events": ["lookup.closed", "lookup.identified", "lookup.progress", "lookup.signal", "lookup.withdrawn"],
  "enabled": true,
  "created_at": "2026-10-05T09:00:00Z",
  "secret": "whsec_..."
}

DELETE /v1/webhook answers 200 with {"object": "webhook_endpoint", "deleted": true}, or "deleted": false when nothing was registered.

POST /v1/webhook/test answers 200 whether or not your endpoint accepted the ping:

{ "object": "webhook_test", "event_id": "evt_...", "delivered": true, "status_code": 204, "error": null }

When delivered is false, status_code is what your endpoint answered (or null if it did not answer) and error is one of unsafe_target, dns_failed, timeout, connection_failed, redirect_not_followed, gone, http_error. One test per 10 seconds; more get 429 rate_limited.

GET /v1/usage:

{ "object": "usage", "limit": 100, "used": 7, "remaining": 93 }

limit and remaining are null when your key has no limit.

Submitting

One signup:

{ "email": "someone@example.com", "external_id": "user_8841", "metadata": { "plan": "trial" }, "country": "US" }

The answer is the lookup object (below) with status 202.

A batch: {"lookups": [ {...}, {...} ]}, up to 100 items. The answer is 202 with one result per item, in order. Each result holds either a lookup or an error, and quota shows what is left on your key:

{
  "object": "batch",
  "results": [
    { "index": 0, "lookup": { "id": "lkp_...", "status": "queued" } },
    { "index": 1, "error": { "code": "lookup_limit_reached", "message": "This API key has reached its lookup limit. Ask LUPO to raise it." } }
  ],
  "quota": { "limit": 100, "used": 100, "remaining": 0 }
}

quota.limit and quota.remaining are null when your key has no limit.

If any item in a batch is malformed, the whole batch is refused with 400 and the error names the item, for example lookups[3].phone.

Sending an address that already has an open lookup returns that lookup with "duplicate": true. It does not count against your limit. The lookup keeps the external_id and metadata of the request that created it, not the ones you just sent, so keep your own map from lookup id to your users.

The lookup object

{
  "id": "lkp_3f9c0a1b2c3d4e5f60718293",
  "object": "lookup",
  "email": "someone@example.com",
  "external_id": "user_8841",
  "metadata": { "plan": "trial" },
  "status": "answered",
  "stage": "watching",
  "final": false,
  "answer": {
    "version": 1,
    "tier": "verified",
    "who": { "name": "Jane Example", "type": "person" },
    "company": null,
    "how_we_know": "This address and the name Jane Example appear together in one public record.",
    "proof": [ { "url": "https://...", "retrieved_at": "2026-10-05T09:12:44Z", "sha256": "9b1f..." } ],
    "answered_at": "2026-10-05T09:13:02Z"
  },
  "reason": null,
  "next_check_at": "2026-10-06T09:00:00Z",
  "created_at": "2026-10-05T09:00:00Z",
  "updated_at": "2026-10-05T09:13:02Z",
  "erased_at": null,
  "model": "River-1"
}

The answer

Answer tiers

• verifieda public record ties this exact address to the named holder. This is the only tier that names someone as identified.
• probablea likely link that is not proven, with the gap spelled out in whats_missing. Off unless your agreement switches it on. Never treat it as identified.
• signala fact tied to the address, with no name (who is null). Useful as a hint, nothing more.
• withdrawnan earlier answer no longer holds (who is null, proof is empty, status stays answered). Stop using it; the lookup stays open for review.
• No answerthe lookup is closed with a reason. Nothing tied the address to a named holder in the time River looked.

Webhooks

PUT /v1/webhook with {"url": "https://..."}. Optional "events": [...] limits what you receive (default: all five lookup events below). A subscription to lookup.identified also receives lookup.withdrawn, so a withdrawal always reaches whoever holds the identified answer. The first registration returns "secret": "whsec_..." once; replacing the URL keeps the secret; "rotate_secret": true issues a new one (shown once). Your URL must be https, use a public host name, and use port 443 or 8443. River does not follow redirects.

Events

Body:

{
  "id": "evt_8e1d2c3b4a5f60718293a4b5",
  "type": "lookup.identified",
  "created_at": "2026-10-05T09:13:02Z",
  "timestamp": "2026-10-05T09:13:02Z",
  "sequence": 2,
  "data": { "id": "lkp_3f9c0a1b2c3d4e5f60718293", "object": "lookup", "...": "the lookup object as it stood" }
}

Headers: webhook-id (the event id), webhook-timestamp (Unix seconds), webhook-signature (v1,<base64>), the Standard Webhooks scheme. Verify with the standardwebhooks library as in the quick start, and reject timestamps more than five minutes old.

Delivery and retries

• A delivery succeeds when your endpoint answers any 2xx within 15 seconds. Answer first and do the work afterwards.
• On any other answer, a timeout or a redirect, River tries again after about 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours, then stops (seven attempts in all). A failed ping is not retried.
• 410 Gone turns your endpoint off. Register it again with PUT /v1/webhook.
• Delivery is at least once: the same event can arrive more than once. Deduplicate on webhook-id.
• Events may arrive out of order. sequence counts up per lookup: if you already handled a higher sequence for that data.id, ignore the older one. GET /v1/lookups/{id} always gives the current state.
• Events go to the endpoint registered when they are sent. Events from before a registration are not replayed.

Idempotency

Send Idempotency-Key: <your id> (1 to 255 printable ASCII characters, no spaces) on POST /v1/lookups. Repeating the same request with the same key returns the same lookups, adds the header Idempotent-Replayed: true, and uses no quota. Reusing a key with a different body is refused with 409 idempotency_conflict. Retry network errors and 5xx answers with the same key.

Limits

Errors

Every error has one shape, and every response carries an X-Request-Id header. Quote it when you contact us.

{ "error": { "code": "forbidden_field", "message": "Phone numbers are not accepted. Send phone_country_code (digits only, for example 44) instead.", "field": "phone" } }

Optional signup fields

Anything you know from the signup can help River check. All optional:

Phone numbers are not accepted (phone, phone_number, mobile and the like are refused): send only phone_country_code. The ip is reduced to its network (the first three parts of an IPv4 address, the first 48 bits of IPv6) and hashed the moment it arrives; the address itself is never stored. Unknown fields are refused by name, so a typo never passes silently.

Inside metadata, a key is refused (400 forbidden_field, naming the key) when it names a phone number, a password or message content. A key is read as words, so userPhone, user_phone and user-phone are the same:

• a key with any of the words phone, phones, cellphone, telephone, msisdn, e164, password, passwords, passwd, pwd, passcode or passphrase, for example user_phone or userPassword;
• a key made only of the words mobile, tel or cell, with number, no or num, for example mobile or tel_no;
• a key made only of the words message, messages, body, text, content, template or sms, with email or mail, for example message, sms_text or email_body;
• the keys phonenumber, mobilenumber, telnumber, cellnumber and contactnumber, with or without separators (contact_number), and any key whose letters start with password or passwd.

Other keys are accepted, for example utm_content, message_id, content_id, body_type and sms_opt_in.

Results page

LUPO can give you a private, read only results link. It opens in any browser, with no login and without your API key, and shows your lookups as they are answered: status, name, holder type, company and a link to the public record, with a CSV download. Each link expires (after 14 days unless agreed otherwise) and LUPO can turn it off at any time. Anyone who has the link can see your results, so share it only inside your company.

Data handling

Once a lookup has been final for 30 days, River erases its address (keeping only a one way fingerprint of it), your metadata, the optional signup fields and everything River gathered for it, and keeps the lookup id, your external_id, its status and dates and the answer you received, shown with email and metadata as null and erased_at set. 30 days is the default term; the term that applies to you is the one set in your agreement.