Guides

Attorneys

Attorney records are built from official bar directories and state filings, then kept accurate by the attorneys themselves through a free claim-and-correct flow. A record you fetch today tells you who the person is, whether they're licensed, where they practice — and, for every field, exactly which source said so.

Ids and the provenance envelope

Attorneys carry API-stable public ids (atty_…) — safe to store as foreign keys. Every response pairs the canonical record with _meta:

"_meta": {
  "fieldSources": {
    "email": {
      "source": "bar_scrape",        // which pipeline asserted the winning value
      "assertionId": "a91f...",       // row in the append-only assertions log
      "assertedAt": 1748419200000,    // Unix ms
      "confidence": 0.95              // 0..1
    }
  },
  "lastReconciledAt": 1748419200000,
  "lastVerifiedAt": 1752019200000     // present once the attorney claims the record
}

Sources include bar_scrape, bar_bulk_export, state_sos, firm_website, attorney_correction, and staff_edit. When sources disagree, a per-field precedence matrix decides: bar directories beat firm websites for bar-status fields; verified attorney corrections beat both.

Endpoints

GET/attorneys/lookup

Search attorneys by name, jurisdiction, bar number, or email. Name search covers canonical + variant names (maiden names, initials, firm-website spellings).

name: string — full-text match on canonical + variant names
jurisdiction: string — two-letter US state code
barNumber: string — exact match, combine with jurisdiction
email: string — exact, case-insensitive
isVerified: boolean — limit to attorney-claimed records
limit: integer 1–100 (default 25)

Example response

{
  "results": [
    {
      "attorney": {
        "id": "atty_iozqS3hOyG4fzddo2aeK",
        "canonicalName": "Jane R. Smith",
        "variantNames": ["Jane Smith", "J. R. Smith"],
        "email": "jsmith@smithlaw.com",
        "phone": "+1 305 555 0100",
        "practiceAreas": ["Civil Litigation", "Insurance"],
        "yearsAdmitted": 2009,
        "currentFirmId": "firm_8Q1yTf3kPw",
        "currentFirm": {
          "id": "firm_8Q1yTf3kPw",
          "canonicalName": "Smith & Alvarez LLP",
          "websiteUrl": "https://smithlaw.com"
        },
        "barAdmissions": [
          {
            "attorneyId": "atty_iozqS3hOyG4fzddo2aeK",
            "jurisdiction": "FL",
            "barNumber": "112233",
            "status": "active",
            "admittedAt": 1230768000000
          }
        ],
        "isVerified": true,
        "claimedAt": 1751500800000,
        "createdAt": 1748419200000
      },
      "_meta": { "fieldSources": { "...": "..." }, "lastReconciledAt": 1752019200000 }
    }
  ]
}

GET/attorneys/{id}

Full canonical view for one attorney — same shape as a lookup result, fetched by public id. 404 not_found if the id doesn't exist or the record is suppressed.

GET/attorneys/{id}/assertions

The append-only provenance log behind the canonical view. One row per source-asserted fact, including superseded values — this is the audit trail.

field: string — filter to one field (e.g. email)
limit: integer 1–500 (default 100)

Example response

{
  "results": [
    {
      "id": "a91f2c...",
      "field": "email",
      "value": "jsmith@smithlaw.com",
      "source": "attorney_correction",
      "assertedAt": 1751587200000,
      "confidence": 1,
      "supersededBy": null            // currently winning
    },
    {
      "id": "a3d08b...",
      "field": "email",
      "value": "jane.smith@oldfirm.com",
      "source": "bar_scrape",
      "sourceUrl": "https://www.floridabar.org/directories/find-mbr/...",
      "assertedAt": 1748419200000,
      "confidence": 0.9,
      "supersededBy": "a91f2c..."     // history preserved, never deleted
    }
  ]
}

Verifying licensure

GET/bar-admissions/verify

Cheapest 'is this attorney actually licensed?' call — one round-trip, one billable unit. verified is true only when the admission status is active.

jurisdiction: string — required, two-letter code
barNumber: string — required

Example response

{
  "verified": true,
  "admission": {
    "jurisdiction": "FL",
    "barNumber": "112233",
    "status": "active",
    "admittedAt": 1230768000000
  },
  "attorney": {
    "id": "atty_iozqS3hOyG4fzddo2aeK",
    "canonicalName": "Jane R. Smith",
    "currentFirmId": "firm_8Q1yTf3kPw"
  }
}

A bar number that doesn't exist returns { "verified": false, "admission": null, "attorney": null } with status 200 — absence is an answer, not an error.