Credits

Overview

SchoolScout uses a credit-based system to control access to intelligence data. Credits are consumed when you "unlock" (scout) entities, revealing their AI-generated insights.

How Credits Work

1. Your organization starts with a credit balance
2. When you unlock a district, school, or contact, credits are deducted
3. Once unlocked, intelligence data is permanently accessible to your organization
4. Credit costs vary by entity type

Credit Costs

Checking Your Balance

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://schoolscout.ai/api/v1/credits

Response:

{
  "balance": {
    "credit_balance": 500,
    "credits_included_monthly": 1000,
    "credit_reset_at": "2026-03-01T00:00:00Z",
    "overage_rate_cents": 0,
    "credits_held": 0
  },
  "usage": [
    {
      "operation": "unlock_district",
      "total_credits": 12,
      "transaction_count": 2
    }
  ],
  "period": {
    "start": "2026-02-01T00:00:00Z",
    "end": "2026-02-18T00:00:00Z"
  }
}

Unlocking Entities

Single Entity

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://schoolscout.ai/api/v1/unlock \
  -d '{"entity_type": "district", "entity_id": "DISTRICT_ID"}'

Bulk Unlock

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://schoolscout.ai/api/v1/unlock \
  -d '{
    "entities": [
      {"entity_type": "district", "entity_id": "ID_1"},
      {"entity_type": "district", "entity_id": "ID_2"},
      {"entity_type": "school", "entity_id": "ID_3"}
    ]
  }'

Response:

{
  "results": [
    {
      "entity_type": "district",
      "entity_id": "ID_1",
      "unlocked": true,
      "credits_charged": 6,
      "already_unlocked": false
    }
  ],
  "total_credits_charged": 15,
  "credits_remaining": 485
}

Credit History

View your spending history:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  'https://schoolscout.ai/api/v1/credits/history?limit=20'

Response includes each transaction plus pagination metadata (total, limit, offset, has_more).

Unlock Order

Contacts require their parent district or school to be unlocked first. If you try to unlock a contact at a locked parent, the API returns 403 PARENT_ENTITY_LOCKED with the parent entity ID and unlock cost.

Typical workflow:

1. Unlock a district or school (6 credits) — reveals intelligence data and makes its contacts visible in search results
2. Unlock individual contacts (2 credits each) — reveals PII (email, phone, LinkedIn)

Districts and schools have no ordering requirement and can be unlocked independently.

What Gets Unlocked

When you unlock a district or school, you gain access to:

• AI Summary -- comprehensive analysis of the entity
• Buying Signals -- contracts, pain points, funding opportunities
• Vendor Stack -- known technology vendors
• Strategic Priorities -- identified goals and initiatives
• Timeline Events -- board meetings, press releases, etc.
• RFPs -- active procurement opportunities
• Contacts -- staff and administrators at the district or school become visible in search results

When you unlock a contact, you gain access to:

• Email -- work email address
• Phone -- work phone number
• LinkedIn URL -- professional profile link
• Enrichment data -- profile summary, key facts, qualification score

Basic demographic data (name, student count, location, etc.) is always visible regardless of unlock status.