The Contractor Verification API
REST API. ~90-second response. Federal records in every US jurisdiction. Integrate Groundcheck into any workflow.
Federal court, OSHA and sanctions records in all 51 jurisdictions, first-party license checks in 38 of 51 (1,823,579 license records held in our own database), and phoenix-entity detection — behind one POST.
The API is in private beta — keys are issued through EarthMove for teams. No public self-serve provisioning yet.
curl -X POST https://api.earthmove.io/v1/trust/verify \
-H "Authorization: Bearer em_live_•••" \
-H "Content-Type: application/json" \
-d '{
"company_name": "Example Roofing & Restoration LLC",
"person_name": "Jordan Example",
"phone": "+1-512-555-0142",
"email": "estimates@example-roofing.example",
"state": "TX"
}'Base URL: https://api.earthmove.io/v1
Quickstart
Three steps from zero to a sourced verdict.
Get a key
Request an API key through EarthMove for teams. You get a sandbox key for testing and a live key once your account is provisioned.
POST a verification
Send the company name (and any of person, phone, email, state) to /v1/trust/verify with your Bearer token. You get a job_id back immediately.
Get the verdict
Poll /v1/trust/result/{job_id} — or register a webhook — for the plain-English verdict, score, signals, and the sources behind each one.
Authentication
Every request authenticates with a secret API key passed as a Bearer token in the Authorization header. Keys are scoped per account and come in two flavors: sandbox (em_test_…) and live (em_live_…).
Keys are issued and rotated from your team dashboard. Treat a live key like a password — it carries the full permissions of your account. Never embed one in client-side code or a public repository.
All traffic is HTTPS-only; requests over plain HTTP are rejected. See security for our key-handling and data-retention posture.
Authorization header
Authorization: Bearer em_live_•••Rotate keys without downtime — an old key stays valid for a short grace window after you mint a new one.
Endpoints
All endpoints are under https://api.earthmove.io/v1. Every endpoint requires a Bearer key. Expand a row for parameters.
Run a verification
Poll a verification's status
Full verdict + signal breakdown
Subscribe to ongoing monitoring
Cancel a monitoring subscription
Fired alerts for your account
Submit a fraud report
Response schema
A completed verdict carries a top-level verdict and score, an array of signals (each with its severity and detail), and the sources behind our signals — so you can show your users exactly where a finding came from.
{
"job_id": "job_8f2a1c4e9b",
"status": "complete",
"verdict": "high_risk",
"score": 28,
"company_name": "Example Roofing & Restoration LLC",
"state": "TX",
"signals": [
{
"type": "license_status",
"result": "expired",
"severity": "high",
"detail": "TX license expired 2025-08-11; no active renewal on file."
},
{
"type": "phoenix_entity",
"result": "match",
"severity": "critical",
"detail": "Same principal tied to a dissolved LA entity with prior complaints."
},
{
// Was "court_judgments" with a county-civil-judgment detail line, plus a "County
// civil court index" source below. Neither lane exists: legal_judgment_against is 1
// evidence row ever and no county court scraper runs. Changed 2026-08-20 to the
// federal docket lane, which does (courtlistener_fed, 141 entities answered).
"type": "federal_court_filings",
"result": "found",
"severity": "medium",
"detail": "Named as defendant in 1 federal civil action, 2024."
}
],
"sources": [
{ "name": "TX TDLR license registry", "checked_at": "2026-06-23T17:04:11Z" },
{ "name": "LA Secretary of State", "checked_at": "2026-06-23T17:04:13Z" },
{ "name": "CourtListener federal dockets", "checked_at": "2026-06-23T17:04:18Z" }
],
"completed_at": "2026-06-23T17:04:21Z"
}How alerts are delivered
Register a webhook URL on your account (or per monitor). When a monitored contractor’s record changes — a license lapses, a new federal filing lands, a phoenix match surfaces — we POST a signed event to your endpoint.
Each delivery is signed with an X-Groundcheck-Signature HMAC-SHA256 header so you can verify it came from us. Failed deliveries are retried with exponential backoff; you can also pull the same events from GET /v1/trust/alerts.
POST https://your-app.example/webhooks/groundcheck
X-Groundcheck-Signature: t=1719162261,v1=8d4e… // HMAC-SHA256
{
"event": "monitor.alert",
"monitor_id": "mon_4b81fa",
"company_name": "Example Roofing & Restoration LLC",
"change": {
"signal": "license_status",
"from": "active",
"to": "expired"
},
"occurred_at": "2026-06-23T17:04:21Z"
}Rate limits & tiers
Limits below are indicative for the private beta and finalized on your plan. Over-limit requests get a 429 with a Retry-After header.
We don’t publish a uptime SLA on this page — see live status and security for availability and incident commitments.
SDKs
The API is plain REST + JSON — usable from any language today. First-party SDKs are on the way.
Node.js
Coming soonA typed TypeScript client wrapping verify, monitor, and webhook-signature verification. Until it ships, call the REST endpoints directly with fetch.
Python
Coming soonA Pythonic client with async support and Pydantic models for the verdict schema. Until it ships, use requests or httpx.
Use cases
Insurance claims
Verify the contractor the moment a claim is assigned — before reconstruction starts. Webhook alerts fire when a contractor’s status changes mid-claim. Entity-level checks keep the review FCRA-clean.
Enterprise procurement
Gate vendor onboarding on a clean verdict. Bulk-verify a supplier list, then subscribe to monitoring so a license lapse or new federal filing surfaces automatically instead of at audit time.
Agency portals
Embed verification into a permitting or consumer-protection portal. Point residents at a live check that runs in every state and stitches entity history across state lines, instead of a single-state license lookup that misses serial actors.
Build verification into your workflow.
Request a private-beta key, or see a verdict first.