API Documentation

Welcome to the Disciply API documentation. This guide will help you integrate with our RESTful API to manage discipleship programs, groups, challenges, and more.

Getting Started

The Disciply API provides programmatic access to your discipleship management platform. To get started with the API, you'll need to:

Register for an account at https://disciply.app/register
Log in to your Disciply account
Subscribe to a Pro plan - API access requires an active Pro subscription
Generate your API token - Follow the authentication steps below

Note: All API requests must be made over HTTPS. Requests made over plain HTTP will fail. API requests without authentication will also fail.

Base URL

https://disciply.app/api

Authentication

The Disciply API uses Laravel Sanctum for authentication. You'll need to include a Bearer token in the Authorization header of your API requests.

Generating Your API Token

To generate a Bearer token for API access:

Log in to your account by making a POST request to the login endpoint:

POST /api/login

POST https://disciply.app/api/login

Request Body

{
  "email": "your-email@example.com",
  "password": "your-password"
}

Response

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "your-email@example.com"
  },
  "token": "1|abcdefghijklmnopqrstuvwxyz1234567890"
}

Using Your API Token

Include the token in the Authorization header of all API requests:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz1234567890

Example Request with cURL

curl -X GET https://disciply.app/api/groups \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Groups API

Manage discipleship groups, memberships, and group activities.

GET List All Groups

GET /api/groups

Retrieve a list of all groups the authenticated user is a member of or has access to.

Response Example

{
  "data": [
    {
      "id": 1,
      "name": "Youth Discipleship Group",
      "description": "Weekly meeting for young adults",
      "member_count": 12,
      "leader": {
        "id": 5,
        "name": "Jane Smith"
      },
      "created_at": "2024-01-15T10:30:00.000000Z"
    }
  ]
}

GET Get Available Groups

GET /api/groups/available

Retrieve a list of groups available for the user to join.

GET Get Single Group

GET /api/groups/{group}

Retrieve detailed information about a specific group.

Parameters

Parameter	Type	Required	Description
`group`	integer	REQUIRED	The ID of the group

POST Create Group

POST /api/groups

Create a new discipleship group.

Request Body

{
  "name": "New Group Name",
  "description": "Group description",
  "organization_id": 1,
  "type": "discipleship"
}

PUT Update Group

PUT /api/groups/{group}

Update an existing group's information.

Parameters

Parameter	Type	Required	Description
`group`	integer	REQUIRED	The ID of the group
`name`	string	OPTIONAL	Updated group name
`description`	string	OPTIONAL	Updated description

DELETE Delete Group

DELETE /api/groups/{group}

Delete a group. Requires group leader or admin privileges.

POST Join Group

POST /api/groups/{group}/join

Join a discipleship group.

Request Body

{
  "group_id": 1
}

POST Leave Group

POST /api/groups/{group}/leave

Leave a discipleship group.

GET Get Group Members

GET /api/groups/{group}/members

Retrieve a list of all members in a group.

Response Example

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "role": "member",
      "joined_at": "2024-01-20T14:30:00.000000Z"
    }
  ]
}

GET Get Group Posts

GET /api/groups/{group}/posts

Retrieve all posts and discussions within a group.

POST Create Group Post

POST /api/groups/{id}/post

Create a new post in a group.

Request Body

{
  "content": "This is my post content",
  "type": "text"
}

POST Rate Group

POST /api/groups/{group}/rate

Submit a rating for a group.

Request Body

{
  "rating": 5,
  "comment": "Great group experience!"
}

Challenges API

Manage discipleship challenges and track user progress through various courses and activities.

GET List All Challenges

GET /api/challenges

Retrieve a list of all available challenges.

Response Example

{
  "data": [
    {
      "id": 1,
      "title": "30-Day Prayer Challenge",
      "description": "Develop a consistent prayer habit",
      "duration_days": 30,
      "difficulty": "beginner",
      "participants_count": 145
    }
  ]
}

GET Get Available Challenges

GET /api/challenges/get_challenges

Retrieve challenges available for the authenticated user.

POST Create Challenge

POST /api/challenges

Create a new challenge. Requires leadership or admin privileges.

Request Body

{
  "title": "Bible Reading Challenge",
  "description": "Read through the entire Bible in 90 days",
  "duration_days": 90,
  "difficulty": "intermediate",
  "organization_id": 1
}

GET Get User Challenge Progress

GET /api/challenges/progress

Retrieve the authenticated user's progress across all challenges.

Response Example

{
  "data": [
    {
      "challenge_id": 1,
      "title": "30-Day Prayer Challenge",
      "progress_percentage": 73,
      "days_completed": 22,
      "days_total": 30,
      "started_at": "2024-01-01T00:00:00.000000Z"
    }
  ]
}

POST Start Challenge

POST /api/challenges/start/{challenge}

Enroll the authenticated user in a challenge.

Parameters

Parameter	Type	Required	Description
`challenge`	integer	REQUIRED	The ID of the challenge

POST Complete Challenge

POST /api/challenges/complete/{challenge}

Mark a challenge as completed.

Parameters

Parameter	Type	Required	Description
`challenge`	integer	REQUIRED	The ID of the challenge

GET Get Challenge Statistics

GET /api/manage/challenges/stats

Retrieve statistics for challenges (admin/leader only).

Response Example

{
  "total_challenges": 15,
  "active_participants": 342,
  "completion_rate": 67.5,
  "most_popular": {
    "id": 1,
    "title": "30-Day Prayer Challenge",
    "participants": 145
  }
}

GET Get Challenge Completions

GET /api/manage/challenges/completions

Retrieve a list of recent challenge completions (admin/leader only).

Journal API

Manage personal journal entries for spiritual growth and reflection.

GET List Journal Entries

GET /api/journal

Retrieve all journal entries for the authenticated user.

Response Example

{
  "data": [
    {
      "id": 1,
      "title": "Morning Devotion Reflection",
      "content": "Today I reflected on...",
      "created_at": "2024-10-14T08:30:00.000000Z",
      "updated_at": "2024-10-14T08:30:00.000000Z"
    }
  ]
}

POST Create Journal Entry

POST /api/journal

Create a new journal entry.

Request Body

{
  "title": "My Journal Entry",
  "content": "Today I learned about...",
  "date": "2024-10-14"
}

Parameters

Parameter	Type	Required	Description
`title`	string	REQUIRED	Title of the journal entry
`content`	string	REQUIRED	Content of the journal entry
`date`	date	OPTIONAL	Date of the entry (defaults to today)

GET Get Single Journal Entry

GET /api/journal/{journal}

Retrieve a specific journal entry.

Parameters

Parameter	Type	Required	Description
`journal`	integer	REQUIRED	The ID of the journal entry

POST Update Journal Entry

POST /api/journal/{journal}

Update an existing journal entry.

Request Body

{
  "title": "Updated Title",
  "content": "Updated content...",
  "_method": "PUT"
}

POST Delete Journal Entry

POST /api/journal/{journal}/delete

Delete a journal entry.

Journey AI API

Leverage AI-powered insights and guidance for your spiritual journey.

GET Get Journey Data

GET /api/journey

Retrieve the user's spiritual journey data and milestones.

Response Example

{
  "data": {
    "total_days": 127,
    "milestones_completed": 8,
    "current_focus": "Prayer and Meditation",
    "journey_data": [
      {
        "date": "2024-10-14",
        "activity": "Morning Prayer",
        "duration_minutes": 30
      }
    ]
  }
}

POST Create Journey Entry

POST /api/journey

Log a new activity or milestone in your spiritual journey.

Request Body

{
  "activity_type": "prayer",
  "duration_minutes": 30,
  "notes": "Focused on gratitude today",
  "date": "2024-10-14"
}

Parameters

Parameter	Type	Required	Description
`activity_type`	string	REQUIRED	Type of activity (prayer, study, service, etc.)
`duration_minutes`	integer	OPTIONAL	Duration in minutes
`notes`	string	OPTIONAL	Additional notes or reflections
`date`	date	OPTIONAL	Date of the activity (defaults to today)

GET Get Journey Progress

GET /api/journey/progress

Retrieve AI-powered insights and progress analytics for your journey.

Response Example

{
  "data": {
    "overall_progress": 67,
    "consistency_score": 8.5,
    "areas_of_growth": [
      "Prayer consistency improved by 45%",
      "Community engagement increased"
    ],
    "ai_recommendations": [
      "Consider joining a prayer group",
      "Continue morning devotion habit"
    ],
    "streak_days": 14
  }
}

Training API

Manage training programs, qualifications, and leadership development.

GET Get Available Qualifications

GET /api/qualifications/get_qualifications

Retrieve all available training qualifications and certifications.

Response Example

{
  "data": [
    {
      "id": 1,
      "title": "Small Group Leader Certification",
      "description": "Comprehensive training for leading small groups",
      "duration_weeks": 8,
      "requirements": [
        "Complete online modules",
        "Attend 2 leadership workshops",
        "Shadow experienced leader"
      ],
      "status": "available"
    }
  ]
}

GET Get User Qualifications Progress

GET /api/qualifications/progress

Retrieve the authenticated user's progress across all qualifications.

Response Example

{
  "data": [
    {
      "qualification_id": 1,
      "title": "Small Group Leader Certification",
      "progress_percentage": 75,
      "modules_completed": 6,
      "modules_total": 8,
      "started_at": "2024-08-01T00:00:00.000000Z",
      "estimated_completion": "2024-11-15"
    }
  ]
}

POST Start Qualification

POST /api/qualifications/start/{qualification}

Enroll the authenticated user in a training qualification.

Parameters

Parameter	Type	Required	Description
`qualification`	integer	REQUIRED	The ID of the qualification

POST Update Qualification Progress

POST /api/qualifications/update-progress/{qualification}

Update progress for a specific qualification module or requirement.

Request Body

{
  "module_id": 3,
  "status": "completed",
  "notes": "Completed all reading materials"
}

Parameters

Parameter	Type	Required	Description
`qualification`	integer	REQUIRED	The ID of the qualification
`module_id`	integer	REQUIRED	The module being updated
`status`	string	REQUIRED	Status (in_progress, completed)

POST Complete Qualification

POST /api/qualifications/complete/{qualification}

Mark a qualification as completed and request certification.

Parameters

Parameter	Type	Required	Description
`qualification`	integer	REQUIRED	The ID of the qualification

POST Assign Training

POST /api/qualifications/assign

Assign a training qualification to one or more users (admin/leader only).

Request Body

{
  "qualification_id": 1,
  "user_ids": [5, 12, 18],
  "due_date": "2024-12-31"
}

Parameters

Parameter	Type	Required	Description
`qualification_id`	integer	REQUIRED	The ID of the qualification to assign
`user_ids`	array	REQUIRED	Array of user IDs to assign training to
`due_date`	date	OPTIONAL	Due date for completion

GET Get Users with Progress

GET /api/qualifications/users-progress

Retrieve training progress for all users in your organization (admin/leader only).

Response Example

{
  "data": [
    {
      "user_id": 5,
      "name": "John Doe",
      "qualifications": [
        {
          "qualification_id": 1,
          "title": "Small Group Leader Certification",
          "progress_percentage": 75,
          "status": "in_progress"
        }
      ]
    }
  ]
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests.

HTTP Status Codes

Code	Meaning
200	OK - Request succeeded
201	Created - Resource successfully created
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing authentication token
403	Forbidden - Authenticated but insufficient permissions
404	Not Found - Resource does not exist
422	Unprocessable Entity - Validation errors
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Standard Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}

Groups API Specific Error Responses

When joining or managing groups, the API returns specific error codes to help you handle business logic errors appropriately.

422 Group Full Error

Returned when attempting to join a group that has reached its maximum member capacity.

Error Response

{
  "message": "This group is full (50/50 members)",
  "error_type": "group_full",
  "group_id": 123,
  "current_members": 50,
  "max_members": 50
}

Fields

Field	Type	Description
`error_type`	string	Always "group_full"
`group_id`	integer	The ID of the full group
`current_members`	integer	Current number of members in the group
`max_members`	integer	Maximum members allowed (configured by system admin)

422 Group Not Live Error

Returned when attempting to join a group that is still in draft mode and not yet accepting members.

Error Response

{
  "message": "This group is not yet live. Please contact your organization administrator.",
  "error_type": "group_not_live",
  "group_id": 123,
  "status": "draft"
}

Fields

Field	Type	Description
`error_type`	string	Always "group_not_live"
`group_id`	integer	The ID of the group
`status`	string	Current group status (draft, active, inactive)

Note: Groups must have a qualified leader assigned before they become active and can accept members.

422 Leader Not Qualified Error

Returned when attempting to assign a leader to a group who has not completed required training/qualifications. This only occurs when the organization has enabled the "enforce_leader_qualifications" setting.

Error Response

{
  "message": "This leader has not completed their required training yet.",
  "error_type": "leader_not_qualified",
  "leader_id": 456,
  "redirect_url": "/manage/team"
}

Fields

Field	Type	Description
`error_type`	string	Always "leader_not_qualified"
`leader_id`	integer	The ID of the unqualified leader
`redirect_url`	string	Suggested URL to manage qualifications/training

Handling this error: Direct users to the training/qualifications page where they can assign required training to the leader or verify their qualification status.

422 Leader Limit Reached Error

Returned when attempting to assign a leader to a group who has already reached their maximum number of active group assignments.

Error Response

{
  "message": "This leader is already assigned to 5 active groups (maximum: 5).",
  "error_type": "leader_limit_reached",
  "leader_id": 456,
  "current_groups": 5,
  "max_groups": 5
}

Fields

Field	Type	Description
`error_type`	string	Always "leader_limit_reached"
`leader_id`	integer	The ID of the leader who has reached their limit
`current_groups`	integer	Number of active groups currently assigned to this leader
`max_groups`	integer	Maximum number of active groups allowed per leader (configured by system admin)

Note: Only active groups count toward the limit. Draft and inactive groups do not count. System administrators can adjust the global limit in the super-admin settings.

Error Handling Best Practices

When building mobile or web applications, we recommend:

Check error_type field: Use the error_type field to programmatically handle different error scenarios rather than parsing the message text.
Display user-friendly messages: The message field contains human-readable text suitable for displaying to end users.
Handle redirects: When a redirect_url is provided, consider navigating the user to that page for resolution.
Show specific details: Use fields like current_members, max_members, current_groups, etc. to provide context to users.
Implement retry logic: For transient errors (5xx codes), implement exponential backoff retry logic.

Example Error Handling (JavaScript)

try {
  const response = await fetch('https://disciply.app/api/groups/join', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ joinCode: 'ABC123' })
  });

  const data = await response.json();

  if (!response.ok) {
    // Handle specific error types
    switch (data.error_type) {
      case 'group_full':
        alert(`Group is full (${data.current_members}/${data.max_members})`);
        break;
      case 'group_not_live':
        alert('This group is not accepting members yet');
        break;
      case 'leader_not_qualified':
        // Redirect to training page
        window.location.href = data.redirect_url;
        break;
      case 'leader_limit_reached':
        alert(`Leader has reached limit: ${data.current_groups}/${data.max_groups}`);
        break;
      default:
        alert(data.message);
    }
    return;
  }

  // Success case
  console.log('Joined group:', data);
} catch (error) {
  console.error('Network error:', error);
}

Support

Need help with the API? We're here to assist you:

Documentation Issues: If you find errors or have suggestions for improving this documentation, please contact us.
Technical Support: For API-related questions or issues, reach out to our support team at support form.
Feature Requests: Have ideas for new API endpoints? We'd love to hear from you through our contact form.

Rate Limits

To ensure fair usage, API requests are rate-limited. Pro plan users receive higher rate limits. Contact support if you need increased limits for your use case.