Data API reference

Every request needs your API key as a Bearer token (or a ?key= query parameter). Subscribe to the Data API plan and a key is minted and emailed to you automatically; generate, rotate, and revoke keys from your dashboard. Keys are shown once - we store only a hash.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://www.hireaiscore.com/api/v1/vendors

Unauthenticated requests get 401; if the feed isn’t licensed on this deployment yet, 503.

120 requests per minute per key. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (epoch seconds). Over the limit returns 429 with a Retry-After header. Need more headroom? Talk to us.

Every profiled vendor (both employer and job-seeker verticals) with overall score, grade, per-category raw scores, and - once it has moved - a trend delta. Full cited evidence lives on the detail endpoint.

{
  "source": "HireAIScore",
  "generatedAt": "2026-07-18T00:00:00.000Z",
  "rubricVersions": { "employer": "v1.0", "jobSeeker": "js-v1.0" },
  "license": "Licensed for internal use …",
  "count": 91,
  "vendors": [
    {
      "slug": "greenhouse",
      "name": "Greenhouse",
      "side": "employer",
      "category": "ats",
      "rubricVersion": "v1.0",
      "score": 67,
      "grade": "D",
      "lastReviewed": "2026-06-07",
      "trend": { "previousScore": 64, "delta": 3, "changedAt": "2026-06-07" },
      "categories": [ { "category": "…", "label": "…", "rawScore": 72, "weight": 0.15 } ],
      "profile": "https://www.hireaiscore.com/vendors/greenhouse",
      "badge": "https://www.hireaiscore.com/vendors/greenhouse/badge",
      "detail": "https://www.hireaiscore.com/api/v1/vendors/greenhouse"
    }
  ]
}

trend is nulluntil a vendor’s score has actually moved (it needs two score snapshots to diff).

The full record behind one score: every scored criterion with its weight, the reviewer, and each cited evidence item with its source URL and capture date - plus evidenceCount, trend, and links to the profile and badge.

{
  "source": "HireAIScore",
  "rubricVersion": "v1.0",
  "vendor": {
    "slug": "greenhouse", "name": "Greenhouse", "score": 67, "grade": "D",
    "lastReviewed": "2026-06-07", "evidenceCount": 24,
    "trend": { "previousScore": 64, "delta": 3, "changedAt": "2026-06-07" },
    "profile": "https://www.hireaiscore.com/vendors/greenhouse",
    "badge": "https://www.hireaiscore.com/vendors/greenhouse/badge"
  },
  "categories": [
    {
      "category": "…", "label": "…", "weight": 0.15, "rawScore": 72,
      "reviewedAt": "2026-06-07", "reviewer": "…",
      "evidence": [ { "type": "…", "sourceUrl": "https://…", "description": "…", "capturedAt": "2026-05-20" } ]
    }
  ]
}

Score moves since ?since=<ISO date> (default: the last 30 days), newest first - poll this instead of diffing the whole list to catch movement.

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://www.hireaiscore.com/api/v1/changes?since=2026-06-01"

{
  "source": "HireAIScore",
  "since": "2026-06-01",
  "count": 2,
  "changes": [
    {
      "slug": "greenhouse", "name": "Greenhouse",
      "previousScore": 64, "score": 67, "delta": 3,
      "changedAt": "2026-06-07",
      "profile": "https://www.hireaiscore.com/vendors/greenhouse",
      "detail": "https://www.hireaiscore.com/api/v1/vendors/greenhouse"
    }
  ]
}

The full score-snapshot series for one vendor, oldest first - chart a vendor’s movement over time.

{
  "source": "HireAIScore",
  "slug": "greenhouse",
  "current": 67,
  "points": 3,
  "history": [
    { "date": "2026-04-01", "score": 64, "rubricVersion": "v1.0" },
    { "date": "2026-06-07", "score": 67, "rubricVersion": "v1.0" }
  ]
}

Register endpoints on your dashboard to get a score.movedPOST whenever a vendor’s score changes - instead of polling /changes. Verify the X-HireAIScore-Signature header (hex HMAC-SHA256 of the raw body, keyed with your endpoint secret).

POST your endpoint
X-HireAIScore-Event: score.moved
X-HireAIScore-Signature: 3a7bd3e2…

{
  "id": "9f1c…",
  "type": "score.moved",
  "createdAt": "2026-07-18T09:00:00.000Z",
  "vendor": { "slug": "greenhouse", "name": "Greenhouse",
    "oldScore": 64, "newScore": 67, "delta": 3 }
}

// verify (Node)
import { createHmac, timingSafeEqual } from "node:crypto";
const expected = createHmac("sha256", SECRET).update(rawBody).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

The feed is licensed for internal use by the subscribing organization - not for redistribution or resale - and asks for attribution to HireAIScore. Scores reflect published and available-on-request evidence at review time and are not legal advice. See the methodology for how scores are derived.