The Contractor Verification API
REST API. ~90-second response. National coverage. Integrate Groundcheck into any workflow.
First-party license checks in 38 states, public-record coverage in all 50 states plus DC, and patent-pending 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": "Summit Roofing & Restoration LLC",
"person_name": "Dale Whitaker",
"phone": "+1-512-555-0142",
"email": "estimates@summit-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 every signal — 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": "Summit 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."
},
{
"type": "court_judgments",
"result": "found",
"severity": "medium",
"detail": "1 civil judgment (breach of contract), 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": "County civil court index", "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 judgment 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": "Summit 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 judgment 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 works in every state 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.