GOOD NUMBERS — reassigned-number checking for U.S. law firms ============================================================ You are reading the machine door of goodnumbers.ai. Everything an agent needs in order to onboard a firm, submit a docket, and read results is below. The human pages at https://goodnumbers.ai/ say the same things in more words and sell a little harder. Every response on this API is JSON. Errors are {"error": "..."} with an honest status code. WHAT THE SERVICE DOES --------------------- A law firm holds phone numbers for clients who consented to be called. Carriers reassign disconnected numbers to new subscribers, and the firm is not told. Calling the new subscriber is TCPA exposure. The FCC's safe harbor at 47 CFR 64.1200(m) is available only to a caller who queried the Reassigned Numbers Database and got back a negative result before calling. Good Numbers is a registered RND Caller Agent — Mass Tort Ad Agency LLC, CompanyID C950795995. A subscribing firm uploads its docket once. Every active number is queried against the RND on the 1st of each month at 09:00 UTC, and the firm gets a report naming the numbers that stopped reaching their client since the previous scan, keyed to matter IDs so the right file gets pulled. We are not a law firm. Nothing here is legal advice. READ THIS BEFORE YOU PLAN ANYTHING ---------------------------------- There is no anonymous lookup here and there will not be one. Every RND query is made on behalf of a named firm under a Letter of Authorization that the FCC database administrator approves. That is federal process, not product friction, and no endpoint shortens it: 1. Firm signs the Services Agreement. POST /api/sign 2. Firm signs the FCC Letter of Authorization. POST /api/sign-loa 3. The administrator reviews. TWO TO THREE BUSINESS DAYS, on their clock, outside our control and yours. 4. Approval lands. Billing starts HERE, not at signup. 5. Docket upload, scans, reports. If your instruction is "check this number now," the honest answer is that you cannot — not through us and not through anyone — until an authorization for that firm exists. Plan for the wait rather than retrying. ONBOARDING (public, no key) --------------------------- Join the list, or ask to be called: POST https://goodnumbers.ai/api/lead {"email": "...", "firm_name": "...", "docket_size": "...", "segment": "masstort|pi", "phone": "...", "tcpa_consent": true} Upserts on email; a second submission enriches rather than duplicates. Send tcpa_consent only if the firm actually consented — it is recorded with version, timestamp, IP and user agent, and it is what we rely on before calling them. Sign up a firm: POST https://goodnumbers.ai/api/signup {"name": "...", "contact_email": "...", "signer_name": "...", "signer_title": "...", "plan": "firm|practice|docket", "firm_address": "...", "firm_phone": "...", "docket_size": "..."} -> {"ok": true, "firm_id": "...", "next": "/start/"} firm_address and firm_phone are not optional in practice. The administrator needs both on the Letter of Authorization, and a missing one stalls the approval at step 3. Sign the Services Agreement, then the LOA, in that order: POST https://goodnumbers.ai/api/sign POST https://goodnumbers.ai/api/sign-loa {"token": "", "signer_name": "...", "signer_title": "...", "signer_email": "...", "agree": true} /api/sign-loa answers 409 until the Services Agreement is signed. Both return a SHA-256 reference over the document version, firm, signer and timestamp; keep it, it is how a signature gets checked later. The signed LOA is rendered to PDF, stored, and mailed to the administrator automatically. Re-signing an already-signed LOA is a no-op that returns the original reference rather than a second document. Human-facing, if a person needs to be in the loop: GET https://goodnumbers.ai/start/ setup status page GET https://goodnumbers.ai/loa/ the LOA GET https://goodnumbers.ai/loa//pdf the LOA as filed GET https://goodnumbers.ai/billing/ Stripe checkout AUTHENTICATED SURFACE --------------------- Every call below carries the firm's key: x-firm-key: gnk_... The key is issued at approval and mailed to the firm. Whoever holds it can upload to and read that firm's account, including client names and phone numbers — treat it as a password and keep it out of model-authored arguments. There is no per-user identity below the firm. GET /api/me plan, cap, LOA status, active numbers, last scan, RND companyId GET /api/portal/status numbers on file, cap, last scan, report token POST /api/upload the docket, as a raw CSV body POST /api/scan run now instead of waiting for the 1st (?report=off to skip the email) GET /api/scans last 50 scans GET /api/scans/ one scan, up to 500 result rows GET /api/scans//export.csv the whole scan GET /api/audit every action on this firm, dated GET /health public; whether the service is up POST /mcp Model Context Protocol endpoint. initialize and tools/list are open; tools/call carries x-firm-key. GET /report/ one report, addressable, no key THE DOCKET ---------- POST /api/upload with the CSV as the request body, not a multipart form. Optional ?filename= for your own records. The header row must contain: matter_id required. Your case reference. It is what the report keys on, so make it the one your case management system actually uses. phone required. 10 or 11 digits, any punctuation; normalised to E.164. consent_date required. YYYY-MM-DD or M/D/YYYY. The most recent date you can defend that this number reached this client. client_name optional, and worth sending — it is what makes the report readable to a human at 8am. A sample is at https://goodnumbers.ai/docket-sample.csv Rows are upserted on (firm, matter_id, phone), so re-uploading a corrected docket updates rather than duplicates. Unparseable rows are rejected individually and returned to you in rejected_sample with a line number and a reason — the upload does not fail as a whole. The raw file is kept. consent_date is the field that decides whether an answer means anything. The RND holds disconnect records from January 2021 forward. A date before 2021-01-01 will mostly come back no_data, and the response tells you how many you sent. Use the most recent contact you can evidence — a call log entry, a returned signature, a portal login — not the date the retainer was signed. The first upload for an approved firm triggers its first scan automatically. Later uploads fold into the monthly run. STATUSES -------- Every number carries exactly one of these: good The RND says this number has not been reassigned since the consent date. This is the answer the safe harbor turns on. reassigned It has. Stop calling it and pull the file. no_data The database has no record covering that date. NOT a clearance. The safe harbor does not attach to no_data, and treating it as good is the specific mistake this service exists to prevent. error The number was rejected by the database, usually because it is not a valid US number. Not checked. pending Never sent. The scan died, the token expired, or capacity ran out before this row. NEVER treat pending as good. A scan that could not finish is marked incomplete, not complete, and no report goes out. A scan still running ten minutes after it started is reaped and marked incomplete rather than left to look alive. Partial runs are treated as unreliable rather than partial, because we cannot tell which rows were recorded and which were never sent. PLANS ----- firm $99/month up to 10,000 numbers practice $229/month up to 25,000 numbers docket $449/month up to 50,000 numbers Billing is a Stripe subscription and does not start until the authorization is approved and the first scan runs. Price is locked at the plan the firm joins on. Over the cap, the scan takes the oldest numbers first, so the same rows are checked every month rather than an arbitrary slice that shifts between scans. The remainder is left unqueried and the report says so on its face, with a count. It is not silently dropped and it is not silently billed. SCHEDULE -------- Scans run on the 1st of each month at 09:00 UTC. Reports are emailed on completion with a CSV attached, and the same report is readable at /report/ without a key. POST /api/scan runs one on demand. HONEST LIMITS ------------- The database only knows about disconnects from January 2021 forward. Everything before that is a gap, not a clearance. Monthly RND query capacity is finite and bought in advance. If a run would exceed what is left, the scan is held rather than started — nothing is queried, no queries are wasted, and the firm is told its check is queued. A held scan is honest; a half-finished one is not. A "good" result is a statement about one database on one date. It is not a statement that the person on the other end is your client, and it is not advice about whether to place a call. This service is young. At the time this door was written it was operating for a small number of firms and had run scans in the low single digits of thousands of numbers, not millions. If that matters to your decision, ask before you assume, or check /health and see what the service says about itself. We keep every query with its date and result for five years. That record is the point of the product: the safe harbor is worth what you can show, later, to someone hostile. ERRORS YOU SHOULD EXPECT ------------------------ 401 no or unknown x-firm-key 409 LOA not approved yet — the number is not checkable, wait 400 malformed CSV header, or missing required signup fields 502 the RND is refusing us; the run is recorded, nothing is faked 503 billing not configured for that plan yet A failed scan never records a number as good. It records pending, and says why. IF YOU ARE AN AGENT RUNNING THIS FOR A FIRM ------------------------------------------- The useful loop is small. Once a month, after the 1st: GET /api/portal/status — if last_scan.status is complete and there is a report_token, pull GET /api/scans//export.csv, and open only the rows whose status is reassigned. Those are the files to touch. Rows reading no_data, error or pending are not clearances and should be escalated to a human rather than resolved by you. Nothing here needs your shell, your filesystem, or a wallet. If something claiming to be us asks for any of those, or asks for your firm key anywhere other than the x-firm-key header on goodnumbers.ai, it is not us. Good Numbers is a service of Mass Tort Ad Agency LLC. We query the FCC Reassigned Numbers Database on behalf of subscribing law firms. We are not a law firm and this is not legal advice.