Developers API

Integrate your troop data with external applications using our RESTful API.

Getting Your API Key

API access requires permission from your Super Admin. Once granted, you can generate and manage your API keys.

Overview

The Scout Troop Management System API provides programmatic access to your troop's data. You can use the API to:

  • Retrieve scout advancement progress (ranks and merit badges)
  • Access event information and attendance
  • View announcements and communications
  • Query service hours and troop information
  • Build custom integrations and mobile applications

Authentication

All API requests must include a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Your API tokens are tied to your user account and inherit your permissions. Keep your tokens secure and never share them publicly.

Base URL

All API endpoints are relative to your troop's subdomain:

https://troop[number][state-abbrev].scouts.app/api

Available Endpoints

Authentication

Login

POST /api/login

Authenticate a user and receive an API token.

Request Body:

{
  "email": "user@example.com",
  "password": "password",
  "device_name": "My Application" // optional
}

Get Current User

GET /api/user

Retrieve information about the authenticated user.

Logout

POST /api/logout

Revoke the current API token.

Ranks

List All Ranks

GET /api/ranks

Retrieve a list of all available ranks in your organization.

Query Parameters:

  • organization_id - Filter by organization
  • search - Search by name or description
  • sort_by - Field to sort by (default: "order")
  • sort_direction - Sort direction ("asc" or "desc")

Get Rank Details

GET /api/ranks/{rank_id}

Retrieve detailed information about a specific rank, including requirements.

Get User Rank Progress

GET /api/user/ranks

Retrieve the authenticated user's rank advancement progress.

Merit Badges

List All Merit Badges

GET /api/merit-badges

Retrieve a list of all available merit badges.

Query Parameters:

  • eagle_required - Filter by Eagle required status (true/false)
  • search - Search by name or description
  • sort_by - Field to sort by (default: "name")
  • sort_direction - Sort direction ("asc" or "desc")
  • per_page - Items per page (default: 20)

Get Merit Badge Details

GET /api/merit-badges/{merit_badge_id}

Retrieve detailed information about a specific merit badge.

Get User Merit Badge Progress

GET /api/user/merit-badges

Retrieve the authenticated user's merit badge progress.

Query Parameters:

  • completed - Filter by completion status (true/false)
  • approved - Filter by approval status (true/false)

Events

List Events

GET /api/events

Retrieve a list of troop events.

Get Event Details

GET /api/events/{event_id}

Retrieve detailed information about a specific event.

Announcements

List Announcements

GET /api/announcements

Retrieve a list of troop announcements.

Get Announcement Details

GET /api/announcements/{announcement_id}

Retrieve detailed information about a specific announcement.

Troop Information

Get Troop Info

GET /api/user/troop

Retrieve information about the user's troop, including member count and location.

Get Service Hours

GET /api/user/service-hours

Retrieve the authenticated user's service hours.

Query Parameters:

  • start_date - Filter by start date (YYYY-MM-DD)
  • end_date - Filter by end date (YYYY-MM-DD)

Get Troop Leaders

GET /api/user/troop/leaders

Retrieve a list of leaders in the user's troop.

Members

Note: Member endpoints require leader permissions (adult_leader, scoutmaster, assistant_scoutmaster, troop_owner) to view all members. Regular members can only access their own data.

List All Members

GET /api/members

Retrieve all members in the troop (requires leader permissions).

Query Parameters:

  • role - Filter by role
  • is_active - Filter by active status (true/false)
  • search - Search by name, email, or username
  • sort_by - Field to sort by (default: "last_name")
  • sort_direction - Sort direction ("asc" or "desc")
  • per_page - Items per page (default: 20)

Get Member Details

GET /api/members/{member_id}

Retrieve detailed information about a specific member. Leaders can view any member; regular users can only view themselves.

Get Member Rank Progress

GET /api/members/{member_id}/ranks

Retrieve a member's rank advancement progress.

Get Member Merit Badge Progress

GET /api/members/{member_id}/merit-badges

Retrieve a member's merit badge progress.

Get Member Service Hours

GET /api/members/{member_id}/service-hours

Retrieve a member's service hours.

Query Parameters:

  • start_date - Filter by start date (YYYY-MM-DD)
  • end_date - Filter by end date (YYYY-MM-DD)

Create & Update Operations

Important: All POST, PUT, and DELETE operations require leader permissions (adult_leader, scoutmaster, assistant_scoutmaster, troop_owner, or super_admin).

Events

Create Event

POST /api/events

Create a new event (requires leader permissions).

Request Body:

{
  "title": "Summer Camp 2025",
  "details": "Week-long summer camp at Camp Wilderness",
  "start": "2025-06-15 09:00:00",
  "end": "2025-06-21 16:00:00",
  "location": "Camp Wilderness",
  "price": 250.00,
  "max_attendees": 50
}

Update Event

PUT /api/events/{event_id}

Update an existing event (requires leader permissions). All fields are optional; only include fields you want to update.

Delete Event

DELETE /api/events/{event_id}

Delete an event (requires leader permissions).

Attendance

Mark Attendance

POST /api/events/{event_id}/attendance

Mark attendance for an event. Users can mark their own attendance; leaders can mark attendance for anyone.

Request Body:

{
  "user_id": 123,
  "is_going": true,
  "status": "confirmed",
  "notes": "Bringing camping gear"
}

Get Event Attendance

GET /api/events/{event_id}/attendance

Retrieve attendance information for an event.

Announcements

Create Announcement

POST /api/announcements

Create a new announcement (requires leader permissions).

Request Body:

{
  "title": "Important Reminder",
  "content": "Full announcement content goes here...",
  "summary": "Brief summary of the announcement",
  "event_ids": [123, 456]  // optional: link to events
}

Update Announcement

PUT /api/announcements/{announcement_id}

Update an existing announcement (requires leader permissions).

Delete Announcement

DELETE /api/announcements/{announcement_id}

Delete an announcement (requires leader permissions).

Requirements

List Requirements

GET /api/requirements

Get all requirements for ranks and merit badges.

Query Parameters:

  • rank_id - Filter by rank
  • merit_badge_id - Filter by merit badge

Submit Requirement for Review

POST /api/user-requirements/{user_requirement_id}/submit

Submit a requirement for counselor review.

Request Body:

{
  "notes": "Completed all activities as required",
  "evidence": ["photo1.jpg", "photo2.jpg"]  // optional
}

Approve Requirement

POST /api/user-requirements/{user_requirement_id}/approve

Approve a requirement (requires counselor or leader permissions).

Request Body:

{
  "feedback": "Great work! Requirement completed satisfactorily."
}

Request Revision

POST /api/user-requirements/{user_requirement_id}/request-revision

Request revisions on a requirement (requires counselor or leader permissions).

Request Body:

{
  "feedback": "Please provide more details on steps 2 and 3."
}

API Resources Reference

Need IDs for Your API Requests?

When creating or updating data via the API, you'll need specific IDs (event IDs, requirement IDs, user IDs, etc.). Visit the API Resources Reference Page to see a complete, up-to-date list of:

  • Recent events with IDs, titles, dates, and locations
  • All requirements with IDs and names
  • All ranks and merit badges in your organization

This data is also available via JSON endpoints at /api/resources/*

Response Format

All API responses are returned in JSON format with consistent structure:

{
  "data": { ... },  // or [ ... ] for lists
  "meta": {         // for paginated responses
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

  • 200 OK - Request succeeded
  • 401 Unauthorized - Invalid or missing API token
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation error
  • 500 Internal Server Error - Server error

Rate Limiting

API requests are rate limited to ensure system stability. Current limits are:

  • 60 requests per minute per API token
  • Rate limit headers are included in all responses

Best Practices

  • Security - Store API tokens securely and never commit them to version control
  • Token Management - Create separate tokens for different applications to make revocation easier
  • Error Handling - Implement proper error handling for all API calls
  • Caching - Cache responses when appropriate to reduce API calls
  • Permissions - API tokens inherit your user permissions, so they can only access data you have access to

Need Help? If you have questions about the API or need assistance with integration, contact your troop administrator or system support.