Leads

Find a lead

GEThttps://api.ruuster.com/v1/leads/lookup

Find your leads by email, phone or CRM id. Returns every match, with links to their activity and emails.

Authentication: x-api-key and x-email headers of an owner or admin
Rate limit: lookup call, 20 per minute per key, within the 120 per minute
Rows count against the daily lead-row quota (50,000 by default)

Only your brokerage's leads are searched.

Query parameters

Name	Type	Description
`email`	string	Case-insensitive. Secondary emails are checked when no lead has it as their main email
`phone`	string	Any format; the last 10 digits are compared. Secondary numbers are checked when no lead has it as their main number
`crmExternalId`	string	Exact match on the lead's id in your CRM

Send exactly one of the three, otherwise 400 invalid_parameter. Lookup by email or phone works even when lead contact details are off; the response then leaves out email and phone.

data.leads lists every match. Each has the short lead form (leadId, names, contact details when on, crmExternalId, crmStatus, crmTags, agentId, createdAt, lastLoginAt), plus matchedOn (email, phone or crmExternalId) and links to the lead's activity and emails. More than one record is normal: the same person can be a registered user and a CRM contact, or be with two agents. No match returns an empty list with 200. For Ruuster's verdict on a lead's email address, use Get a lead's email status.

Request

curl -s "https://api.ruuster.com/v1/leads/lookup?phone=(520)%20555-0142" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"

const res = await fetch("https://api.ruuster.com/v1/leads/lookup?phone=(520)%20555-0142", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);

import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/leads/lookup?phone=(520)%20555-0142",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])

{ "ok": true, "data": { "leads": [ { "leadId": "user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04", "firstName": "Sam", "lastName": "Lee", "email": "sam.lee@example.com", "phone": "+15205550142", "crmExternalId": "48213", "crmStatus": "Showing Homes Nurture", "crmTags": ["buyer", "tucson"], "agentId": "7c1e9b42-3d85-4a6f-9e07-1b2c8d4f5a69", "createdAt": "2026-09-21T18:20:05Z", "lastLoginAt": "2026-09-30T02:11:40Z", "matchedOn": "phone", "links": { "activity": "/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/activity", "emails": "/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/emails" } } ] }, "meta": { "brokerageId": "4f6c2a9e-8d31-4b57-9a0e-2c7d5e1b8f43" } }

Find a lead

Query parameters

Response