College Sports Directory – API Documentation

GET /schools

List schools with filtering, sorting, and pagination.

Example

curl -H "X-CSD-API-Key: YOUR_KEY" \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/schools?state=AL&per_page=5"

GET /schools/{id}

Get a single school by ID, including staff count.

Example

curl -H "X-CSD-API-Key: YOUR_KEY" \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/schools/45"

GET /schools/{id}/staff

Get staff members for a specific school.

Example

curl -H "X-CSD-API-Key: YOUR_KEY" \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/schools/45/staff?department=Football"

GET /staff

List all staff members with filtering, sorting, and pagination.

Example

curl -H "X-CSD-API-Key: YOUR_KEY" \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/staff?department=Football&per_page=10"

GET /staff/{id}

Get a single staff member with their associated school.

Example Response

{
  "success": true,
  "data": {
    "id": 101,
    "full_name": "John Smith",
    "title": "Head Football Coach",
    "sport_department": "Football",
    "email": "[email protected]",
    "phone": "(205) 348-1234",
    "school": {
      "id": 45,
      "school_name": "University of Alabama",
      "city": "Tuscaloosa",
      "state": "AL",
      "school_divisions": "NCAA D1"
    }
  }
}

GET /search

Search across both schools and staff in a single request.

Example

curl -H "X-CSD-API-Key: YOUR_KEY" \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/search?q=Alabama"

Response

{
  "success": true,
  "data": {
    "schools": [ { "id": 1, "school_name": "University of Alabama", ... } ],
    "staff": [ { "id": 101, "full_name": "...", "school_name": "University of Alabama" } ],
    "totals": { "schools": 3, "staff": 42 }
  }
}

GET /stats

Get summary statistics for the directory.

Returns record counts and last-updated timestamps. No parameters required.

Example

curl -H "X-CSD-API-Key: YOUR_KEY" \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/stats"

Response

{
  "success": true,
  "data": {
    "counts": {
      "schools": 2104,
      "staff": 137965,
      "states_represented": 54,
      "divisions": 9,
      "school_types": 5,
      "departments": 11046
    },
    "last_updated": {
      "schools": "2025-11-12T14:26:59Z",
      "staff": "2026-02-18T11:57:32Z"
    }
  },
  "meta": {
    "timestamp": "2026-02-18T14:30:00Z"
  }
}

GET /events

Query the event log to see recent changes. Use the since parameter to catch up on missed webhooks.

Webhook Management

Register webhooks to receive real-time HTTP POST notifications when records change.

POST /webhooks

Register a new webhook.

curl -X POST -H "X-CSD-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhook","events":["school.created","staff.updated"],"name":"My App"}' \
  "https://www.collegesportsdirectory.com/wp-json/csd/v1/webhooks"

Returns the webhook ID and a secret for signature verification (shown once).

GET /webhooks

List your registered webhooks.

PUT /webhooks/{id}

Update a webhook's URL, events, or active status.

DELETE /webhooks/{id}

Delete a webhook.

Webhook Payload

When an event occurs, CSD sends an HTTP POST to your registered URL:

{
  "event": "school.updated",
  "timestamp": "2026-02-18T14:30:00Z",
  "data": {
    "id": 45,
    "school_name": "University of Alabama",
    ...
  }
}

Signature Verification

Each request includes an X-CSD-Signature header containing an HMAC-SHA256 hash of the request body using your webhook secret:

# PHP verification example
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CSD_SIGNATURE'];
$expected = hash_hmac('sha256', $payload, $your_secret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
}

Failure Handling

If your endpoint returns a non-2xx status or times out, the failure count increments. After 10 consecutive failures, the webhook is auto-disabled. Re-enable it via PUT /webhooks/{id} with {"is_active": true}.