REST API reference

Authentication

Every request carries an API key in the Authorization header. Admins create keys in the dashboard under Settings → Developers; the full key is shown once at creation and only a hash is stored. Keys are read-only and scoped to one company (plus its tracked competitors). Revoke a key any time from the same page.

curl https://app.teampredict.ai/api/v1/me \
  -H "Authorization: Bearer tp_your_api_key"

Rate limits & errors

Each key may make 120 requests per minute. Beyond that the API answers 429 with a Retry-After header. Errors always share one JSON shape:

{ "error": "Human-readable message", "code": "OPTIONAL_MACHINE_CODE" }

• 400 - invalid parameter (the message says which)
• 401 - missing, malformed, unknown, or revoked API key
• 402 - the organization has no active subscription or trial (SUBSCRIPTION_INACTIVE)
• 404 - the resource does not exist or is outside your key's scope
• 429 - rate limited; wait Retry-After seconds

Pagination

List endpoints take page and pageSize (default 25, max 100) and respond with { items, total, page, pageSize, hasMore }. Iterate while hasMore is true.

Endpoints

Example: list employees

curl "https://app.teampredict.ai/api/v1/employees?tracked=true" \
  -H "Authorization: Bearer tp_your_api_key"

{
  "items": [
    {
      "id": 123,
      "organizationId": 7,
      "name": "Jordan Lee",
      "title": "Staff Engineer",
      "location": "Austin, Texas",
      "department": "Engineering",
      "linkedinUrl": "https://www.linkedin.com/in/jordanlee",
      "profileImageUrl": "https://...",
      "tracked": true,
      "status": "active",
      "trackingStartedAt": "2026-03-02T15:11:08.000Z",
      "createdAt": "2026-03-02T15:11:08.000Z",
      "latestChange": {
        "riskScore": 0.82,
        "riskLevel": "high",
        "changeType": "open_to_work",
        "detectedAt": "2026-07-27T09:14:02.511Z"
      }
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 25,
  "hasMore": true
}

riskLevel maps the 0-1 AI risk score to the dashboard's tiers: high at 75%+, watch at 50-74%, low below that. Departures carry no numeric score and read as high.

Example: the risk-change feed

curl "https://app.teampredict.ai/api/v1/changes?minRiskScore=0.5&since=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer tp_your_api_key"

{
  "id": 18342,
  "organizationId": 7,
  "employeeId": 123,
  "employeeName": "Jordan Lee",
  "changeType": "open_to_work",
  "changedFields": "open_to_work; off; on",
  "riskScore": 0.82,
  "riskLevel": "high",
  "summary": "Turned on Open to Work and rewrote their headline.",
  "factors": ["Open to Work badge enabled", "Headline rewritten"],
  "followerCount": 1873,
  "detectedAt": "2026-07-27T09:14:02.511Z"
}

Change categories: profile_update, headline_change, title_change, open_to_work, new_skills, location_change, photo_or_summary, edit_activity, experience_change, employee_departed.

Example: poaching opportunities

Competitor workspaces reuse every endpoint: list them once, then pass a workspace id as organizationId to /v1/employees or /v1/changes. The same risk scores read as “may be open to a move” there.

# 1. List competitor workspaces
curl https://app.teampredict.ai/api/v1/competitors \
  -H "Authorization: Bearer tp_your_api_key"

# 2. Read a competitor's people (poaching lens) by organizationId
curl "https://app.teampredict.ai/api/v1/employees?organizationId=9" \
  -H "Authorization: Bearer tp_your_api_key"