DaChurchMan API Documentation

API Overview

The DaChurchMan API provides endpoints for member authentication and registration across multiple churches. It uses a two-server architecture:

  • Central API Server: https://api4mobile.dachurchman.com/
  • Church-Specific Server: https://test.dachurchman.com/

Important Notes:

  • All input must be in JSON format.
  • The server URL must be hard-coded in the mobile app.
Authentication

Authentication is handled through a two-step process:

  1. Initiate login with email (generates OTP)
  2. Verify OTP to complete authentication

Member Signup Flow

Important Note: The Church-Specific Server URL must be hard-coded in the mobile app and sent with other request parameters to the Central API Server. This allows the system to easily point to the needed server for each request.

  1. The Mobile App (Client) interacts with two types of servers:
    • Central API Server: https://api4mobile.dachurchman.com
    • Church-Specific Server(s): https://test.dachurchman.com (Note: There could be multiple church-specific servers connected to this test server)
  2. Login Process:
    1. The app sends a login request to the Central API Server (https://api4mobile.dachurchman.com) with email, church_id, and the hard-coded server_url.
    2. The Central API Server generates an OTP and stores it temporarily.
    3. The Central API Server then forwards this information to the appropriate Church-Specific Server (determined by the provided server_url) to initiate the signup process.
    4. The Church-Specific Server checks if the email exists in the church database and sends the OTP to the user's email.
    5. The Church-Specific Server responds back to the Central API Server with church information.
    6. The Central API Server sends this information back to the app.
  3. OTP Verification:
    1. The app sends the OTP to the Central API Server (https://api4mobile.dachurchman.com) for verification, along with the hard-coded server_url.
    2. The Central API Server checks if the OTP is correct.
    3. If correct, the Central API Server forwards the verification request to the appropriate Church-Specific Server (determined by the provided server_url).
    4. The Church-Specific Server verifies the OTP again, creates new signups if needed, and sends back detailed user information.
    5. The Central API Server receives this information and sends it back to the app.

In essence:

  • The Central API Server (https://api4mobile.dachurchman.com) acts as a gateway or intermediary.
  • The Church-Specific Server(s) (https://test.dachurchman.com) handle the actual church-specific data and operations. Multiple church-specific servers may be connected to this test environment.

Both types of servers handle OTP in different ways:

  • The Central API Server generates and initially verifies the OTP.
  • The Church-Specific Server stores the OTP, sends it to the user, and performs the final verification.

This two-server approach allows for centralized control (via the Central API Server) while maintaining church-specific operations (via the Church-Specific Servers). It's a bit complex, but it allows for flexibility in managing multiple churches through a single app. The test environment (https://test.dachurchman.com) may represent multiple church-specific servers, allowing for testing and development of multi-church scenarios.

Multi-Church Signup Process

When a member belongs to multiple churches, the system automatically sets them up for all their churches during the initial signup. Here's how it works:

  1. A member belongs to Church A and Church B.
  2. They initially sign up for the mobile app through Church A.
  3. When they verify their OTP, the system will:
    1. Create a MobileAppSignup entry for Church A (if it doesn't exist).
    2. Also create a MobileAppSignup entry for Church B (since they're a member there too).
  4. This way, the member is now set up to use the mobile app for both churches without needing to go through the signup process again.

This multi-church signup process ensures a seamless experience for members who are part of multiple churches, allowing them to access all their church accounts through a single app signup.

API Endpoints

1. Login (OTP Generation)

POST https://api4mobile.dachurchman.com/api/register

Parameters (JSON):

{
  "email": "string",
  "server_url": "string"
}

Response:

{
  "message": "OTP sent successfully",
  "email": "[email protected]",
  "is_multiple_churches": true
}

2. Verify OTP

POST https://api4mobile.dachurchman.com/api/verify-otp

Parameters (JSON):

{
  "email": "string",
  "otp": "string",
  "server_url": "string",
  "church_id": "integer|null"
}

Response:

{
  "message": "Signup successful. You can switch between your churches in the app.",
  "token": "access_token_here",
  "churches": [
    {
      "id": 1,
      "name_of_church": "Example Church",
      "location": "Example Location",
      "email": "[email protected]"
    }
  ],
  "current_church": {
    "id": 1,
    "name_of_church": "Example Church",
    "location": "Example Location",
    "email": "[email protected]"
  },
  "user_data": {
    "id": 1,
    "member_id": "MEMBER001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "church_id": 1
  },
  "is_multiple_churches": true,
  "new_signups": []
}

3. Initiate Signup (Church-Specific Server)

POST https://test.dachurchman.com/api/signup/initiate

Parameters (JSON):

{
  "email": "string",
  "otp": "string",
  "expiry_time": "string"
}

Response:

{
  "message": "OTP sent successfully",
  "churches": [
    {
      "id": 4,
      "name_of_church": "Galilea Methodist Society",
      "location": "Galilea",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "name_of_church": "Testing Account",
      "location": "Accra",
      "email": "[email protected]"
    }
  ]
}

4. Verify Signup (Church-Specific Server)

POST https://test.dachurchman.com/api/signup/verify

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "otp": "string"
}

Response:

{
  "message": "Signup successful. You can now switch between your churches in the app.",
  "churches": [
    {
      "id": 4,
      "name_of_church": "Galilea Methodist Society",
      "location": "Galilea",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "name_of_church": "Testing Account",
      "location": "Accra",
      "email": "[email protected]"
    }
  ],
  "current_church": {
    "id": 4,
    "name_of_church": "Galilea Methodist Society",
    "location": "Galilea",
    "email": "[email protected]"
  },
  "new_signups": [],
  "members": [
    {
      "id": 1,
      "member_id": "MEMBER001",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "church_id": 4
    }
  ]
}

5. Switch Church

POST https://api4mobile.dachurchman.com/switch-church

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string"
}

Response:

{
  "message": "Church switched successfully",
  "current_church": {
    "id": 2,
    "name_of_church": "New Church",
    "location": "New Location",
    "email": "[email protected]"
  },
  "churches": [
    {
      "id": 1,
      "name_of_church": "Example Church",
      "location": "Example Location",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "name_of_church": "New Church",
      "location": "New Location",
      "email": "[email protected]"
    }
  ],
  "user_data": {
    "id": 1,
    "member_id": "MEMBER001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "church_id": 2
  },
  "is_multiple_churches": true
}

This endpoint allows users to switch between their associated churches without needing to log out and log back in. The server will verify that the user is a member of the requested church before allowing the switch.

Error Responses:

  • 403: User is not a member of the requested church
  • 404: Requested church not found
  • 422: Validation error (missing or invalid parameters)
  • 500: Server error

6. Logout

POST https://api4mobile.dachurchman.com/logout

{
  "message": "Successfully logged out"
}

7. Refresh Token

POST https://api4mobile.dachurchman.com/refresh-token

{
  "token": "new_access_token_here"
}

Fetch Announcements

GET https://api4mobile.dachurchman.com/api/announcements

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string"
}

Response:

{
  "message": "Announcements fetched successfully",
  "announcements": [
    {
      "id": 1,
      "church_id": 123,
      "title": "Sunday Service",
      "announcement_details": "<p>Join us this Sunday for a special service.</p>",
      "is_scheduled": 0,
      "publish_date": "2024-09-06",
      "publish_time": "09:00:00",
      "created_by": 1,
      "expires_at": "2024-09-13 00:00:00",
      "created_at": "2024-09-05T10:00:00.000000Z",
      "updated_at": "2024-09-05T10:00:00.000000Z"
    }
  ]
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves announcements that are not scheduled (is_scheduled = 0) and have not expired.
  • Announcements are ordered by creation date, with the most recent first.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • The announcement_details field may contain HTML content. Render this content safely in your application.
  • If no announcements meet the criteria, an empty array will be returned in the announcements field.
  • Error responses will include a descriptive message to help diagnose the issue.

Fetch Events

GET https://api4mobile.dachurchman.com/api/events

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "page": "integer (optional, default: 1)",
  "per_page": "integer (optional, default: 10, max: 50)"
}

Response:

{
  "message": "Events fetched successfully",
  "events": [
    {
      "id": 1,
      "church_id": 123,
      "event_date": "2024-05-15",
      "title": "Sunday Service",
      "about_event": "<p>Join us for our weekly Sunday service.</p>",
      "start_time": "10:00:00",
      "end_time": "12:00:00",
      "venue": "Main Church Hall",
      "dress_code": "Smart Casual",
      "speaker": "Pastor John Doe",
      "cover_photo": "events/sunday-service-cover.jpg",
      "created_at": "2024-05-01T10:00:00.000000Z",
      "updated_at": "2024-05-01T10:00:00.000000Z",
      "is_scheduled": 0,
      "publish_date": "2024-05-01",
      "publish_time": "09:00:00",
      "status": 1
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_events": 47
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves upcoming events (event_date is today or in the future) that are not scheduled (is_scheduled = 0).
  • Events are ordered by event_date (ascending) and then by start_time (ascending).
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • The about_event field may contain HTML content. Render this content safely in your application.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the event list.
  • If no events meet the criteria, an empty array will be returned in the events field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • Scheduled events are automatically published when their publish_date and publish_time arrive, using a separate scheduler process.

Fetch Text Devotions

GET https://api4mobile.dachurchman.com/api/devotions

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "page": "integer (optional, default: 1)",
  "per_page": "integer (optional, default: 10, max: 50)"
}

Response:

{
  "message": "Devotions fetched successfully",
  "devotions": [
    {
      "id": 1,
      "church_id": 123,
      "title": "Daily Strength",
      "main_scripture": "Psalm 23:1",
      "keynote_passage": "The Lord is my shepherd; I shall not want.",
      "keynote_bible_verse": "Psalm 23:1",
      "message": "<p>Today's devotion focuses on God's provision...</p>",
      "scripture_reference_1": "John 10:11",
      "scripture_reference_2": "Isaiah 40:11",
      "scripture_reference_3": "1 Peter 5:7",
      "prayer": "Dear Lord, thank you for being our shepherd...",
      "further_studies": "Ezekiel 34:11-16, John 10:1-18",
      "author_name": "Pastor Jane Doe",
      "public_visibility": "Yes",
      "publish_date": "2024-05-15",
      "publish_time": "06:00:00",
      "is_scheduled": 0,
      "author_photo": "uploads/mobile-app/devotion/author_jane_doe.jpg",
      "cover_photo": "uploads/mobile-app/devotion/daily_strength_cover.jpg",
      "created_at": "2024-05-14T10:00:00.000000Z",
      "updated_at": "2024-05-14T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_devotions": 47
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves upcoming devotions (publish_date is today or in the future) that are not scheduled (is_scheduled = 0).
  • Devotions are ordered by publish_date (ascending) and then by publish_time (ascending).
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • The message field may contain HTML content. Render this content safely in your application.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the devotion list.
  • If no devotions meet the criteria, an empty array will be returned in the devotions field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • Scheduled devotions are automatically published when their publish_date and publish_time arrive, using a separate scheduler process.

Fetch Podcasts

GET https://api4mobile.dachurchman.com/api/podcasts

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "page": "integer (optional, default: 1)",
  "per_page": "integer (optional, default: 10, max: 50)"
}

Response:

{
  "message": "Podcasts fetched successfully",
  "podcasts": [
    {
      "id": 1,
      "church_id": 123,
      "title": "Weekly Sermon",
      "description": "<p>This week's sermon on faith and perseverance.</p>",
      "audio_url": "podcasts/weekly-sermon-2024-05-15.mp3",
      "duration": "00:45:30",
      "speaker": "Pastor John Doe",
      "cover_image": "podcasts/weekly-sermon-cover.jpg",
      "publish_date": "2024-05-15",
      "publish_time": "09:00:00",
      "is_scheduled": 0,
      "created_at": "2024-05-14T10:00:00.000000Z",
      "updated_at": "2024-05-14T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_podcasts": 47
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves upcoming podcasts (publish_date is today or in the future) that are not scheduled (is_scheduled = 0).
  • Podcasts are ordered by publish_date (ascending) and then by publish_time (ascending).
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • The description field may contain HTML content. Render this content safely in your application.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the podcast list.
  • If no podcasts meet the criteria, an empty array will be returned in the podcasts field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • Scheduled podcasts are automatically published when their publish_date and publish_time arrive, using a separate scheduler process.

Fetch Streams

GET https://api4mobile.dachurchman.com/api/streams

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "page": "integer (optional, default: 1)",
  "per_page": "integer (optional, default: 10, max: 50)"
}

Response:

{
  "message": "Streams fetched successfully",
  "streams": [
    {
      "id": 1,
      "church_id": 123,
      "title": "Sunday Service Live Stream",
      "description": "<p>Join us for our live Sunday service.</p>",
      "stream_url": "https://streaming.example.com/live/sunday-service",
      "stream_type": "live",
      "duration": "02:00:00",
      "thumbnail": "streams/sunday-service-thumbnail.jpg",
      "publish_date": "2024-05-15",
      "publish_time": "09:30:00",
      "is_scheduled": 0,
      "created_at": "2024-05-14T10:00:00.000000Z",
      "updated_at": "2024-05-14T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_streams": 47
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves upcoming streams (publish_date is today or in the future) that are not scheduled (is_scheduled = 0).
  • Streams are ordered by publish_date (ascending) and then by publish_time (ascending).
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • The description field may contain HTML content. Render this content safely in your application.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the stream list.
  • If no streams meet the criteria, an empty array will be returned in the streams field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • Scheduled streams are automatically published when their publish_date and publish_time arrive, using a separate scheduler process.

Fetch MarketPlace Entries

GET https://api4mobile.dachurchman.com/api/market-place

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "page": "integer (optional, default: 1)",
  "per_page": "integer (optional, default: 10, max: 50)"
}

Response:

{
  "message": "MarketPlace entries fetched successfully",
  "market_place_entries": [
    {
      "id": 1,
      "church_id": 123,
      "member_id": 456,
      "company_name": "Example Services Co.",
      "primary_phone_number": "+1234567890",
      "secondary_phone_number": "+0987654321",
      "email": "[email protected]",
      "location": "123 Main St, City, State, ZIP",
      "services": ["Service 1", "Service 2", "Service 3"],
      "logo": "uploads/mobile-app/market/example_logo.jpg",
      "start_date": "2024-05-15",
      "end_date": "2024-12-31",
      "public_visibility": 1,
      "created_at": "2024-05-14T10:00:00.000000Z",
      "updated_at": "2024-05-14T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_entries": 47
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves active MarketPlace entries (current date is between start_date and end_date).
  • Entries are ordered by start_date (ascending) and then by creation date (descending).
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • The services field contains an array of services offered by the company.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the MarketPlace entries list.
  • If no entries meet the criteria, an empty array will be returned in the market_place_entries field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • The logo field contains the path to the company's logo image. Ensure to prepend the appropriate base URL when displaying images.

Fetch Professional Directory Entries

GET https://api4mobile.dachurchman.com/api/professional-directory

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "page": "integer (optional, default: 1)",
  "per_page": "integer (optional, default: 10, max: 50)"
}

Response:

{
  "message": "Professional Directory entries fetched successfully",
  "professional_directory": [
    {
      "id": "GMS/2022/000014",
      "member_id": "GMS/2022/000014",
      "church_id": 123,
      "title": "Fada",
      "first_name": "LAWRENCIA",
      "last_name": "OTOO",
      "email": "[email protected]",
      "primary_phone_number": "248385445",
      "residential_address": "P.O BOX OH 378,KASOA",
      "occupation": "TEACHER",
      "employment_institution": "HOPE OF GLORY MONTESSORI CENTRE",
      "educational_level": "Doctoral or Equivalent",
      "picture": "path/to/picture.jpg",
      "professional_directory": 1,
      "system_status": "Active"
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_entries": 47
}

Important Notes:

  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the request body, not as an Authorization header for this specific endpoint.
  • This endpoint retrieves members where professional_directory = 1 and system_status = 'Active'.
  • Entries are ordered by member_id in ascending order.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The email parameter is used to verify the user's association with the specified church.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the Professional Directory entries list.
  • If no entries meet the criteria, an empty array will be returned in the professional_directory field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • The picture field contains the path to the member's profile picture. Ensure to prepend the appropriate base URL when displaying images.
  • Sensitive information such as contact details should be handled with care and in compliance with data protection regulations.
  • Only active members (system_status = 'Active') are included in the professional directory results.

Fetch Membership Information

1. Fetch Personal Information

GET https://api4mobile.dachurchman.com/api/membership/personal-info

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string

Response:

{
  "message": "Personal information fetched successfully",
  "personal_info": {
    "id": integer,
    "member_id": string,
    "title": string,
    "alias": string|null,
    "first_name": string,
    "other_names": string|null,
    "last_name": string,
    "place_of_birth": string,
    "email": string,
    "primary_phone_number": string,
    "secondary_phone_number": string|null,
    "residential_address": string,
    "landmark": string|null,
    "hometown": string,
    "nationality": string,
    "marital_status": string,
    "name_of_spouse": string|null,
    "date_married": date|null,
    "previous_name": string|null,
    "gender": string,
    "dob": date,
    "age_group": string
  }
}

2. Fetch Church Information

GET https://api4mobile.dachurchman.com/api/membership/church-info

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string

Response:

{
  "message": "Church information fetched successfully",
  "church_info": {
    "bible_study_group": integer,
    "year_joined_church": integer|null,
    "leader_position": string|null,
    "previous_church": string|null,
    "leader_position_in_previous": string|null,
    "special_gifts": string|null,
    "is_baptised": boolean,
    "place_baptised": string|null,
    "baptized_by": string|null,
    "date_baptised": date|null,
    "is_confirmed": boolean,
    "confirmed_by": string|null,
    "place_confirmed": string|null,
    "date_confirmed": date|null,
    "member_type": integer,
    "date_joined": date,
    "time_joined": time
  }
}

3. Fetch Family Information

GET https://api4mobile.dachurchman.com/api/membership/family-info

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string

Response:

{
  "message": "Family information fetched successfully",
  "family_info": [
    {
      "id": integer,
      "member_id": integer,
      "relation": string,
      "name": string,
      "number": string|null,
      "occupation": string|null,
      "address": string|null,
      "pic": string|null
    },
    // ... more family relations
  ]
}

Important Notes for Family Information:

  • The family_info array contains all family relations associated with the member.
  • Each family relation includes the following fields:
    • id: Unique identifier for the family relation record
    • member_id: ID of the member to whom this family relation belongs
    • relation: The relationship type (e.g., "Brother", "Mother", "Father")
    • name: Full name of the family member
    • number: Contact number of the family member (can be null)
    • occupation: Occupation of the family member (can be null)
    • address: Residential address of the family member (can be null)
    • pic: Path to a picture of the family member, if available (can be null)
  • The pic field, if not null, contains the path to the family member's picture. Ensure to prepend the appropriate base URL when displaying images.
  • Fields that are null indicate that the information is not available or has not been provided.
  • The number of family relations can vary for each member.

4. Fetch Profession and Education Information

GET https://api4mobile.dachurchman.com/api/membership/profession-education-info

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string

Response:

{
  "message": "Profession and Education information fetched successfully",
  "profession_and_education_info": {
    "employment_status": string,
    "educational_level": string,
    "occupation": string,
    "start_date": date|null,
    "end_date": date|null,
    "employment_institution": string|null,
    "professional_directory": boolean
  }
}

Important Notes:

  • All endpoints require authentication. The token should be included in the query string.
  • The email and church_id are used to identify the correct member record to fetch.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • If a member is not found for the given email and church_id combination, a 404 error will be returned.
  • Date fields are in the format "YYYY-MM-DD" and time fields are in the format "HH:MM:SS".
  • Boolean fields are represented as true or false.
  • The professional_directory field in the Profession and Education info indicates whether the member is listed in the professional directory.
  • Error responses will include a descriptive message to help diagnose the issue.
  • These endpoints are designed for personal use only. Members can only fetch their own records.
  • Sensitive information should be handled with care and in compliance with data protection regulations.

Update Membership Information

1. Update Personal Information

PUT https://api4mobile.dachurchman.com/api/update-personal-info

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "title": "string",
  "alias": "string|null",
  "first_name": "string",
  "other_names": "string|null",
  "last_name": "string",
  "place_of_birth": "string",
  "primary_phone_number": "string",
  "secondary_phone_number": "string|null",
  "residential_address": "string",
  "landmark": "string|null",
  "hometown": "string",
  "nationality": "string",
  "marital_status": "string",
  "name_of_spouse": "string|null",
  "date_married": "date|null",
  "previous_name": "string|null",
  "gender": "string",
  "dob": "date",
  "age_group": "string"
}

Response:

{
  "message": "Personal information updated successfully",
  "member": {
    // Updated member object
  }
}

2. Update Church Information

PUT https://api4mobile.dachurchman.com/api/update-church-info

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "bible_class": "integer",
  "year_joined_church": "integer|null",
  "leadership_position": "string|null",
  "previous_church": "string|null",
  "previous_church_leadership_position": "string|null",
  "special_gift": "string|null",
  "baptism": "boolean",
  "place_baptized": "string|null",
  "baptized_by": "string|null",
  "date_baptized": "date|null",
  "confirmed": "boolean",
  "confirmed_by": "string|null",
  "place_confirmed": "string|null",
  "membership_status": "integer"
}

Response:

{
  "message": "Church information updated successfully",
  "member": {
    // Updated member object
  }
}

Update Family Information

PUT https://api4mobile.dachurchman.com/api/update-family-info

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "family_members": [
    {
      "id": "integer|null",
      "relation": "string",
      "name": "string",
      "number": "string|null",
      "occupation": "string|null",
      "address": "string|null"
    },
    // ... more family members
  ]
}

Response:

{
  "message": "Family information updated successfully",
  "family_info": [
    {
      "id": integer,
      "member_id": integer,
      "relation": string,
      "name": string,
      "number": string|null,
      "occupation": string|null,
      "address": string|null,
      "pic": string|null,
      "created_at": datetime,
      "updated_at": datetime
    },
    // ... more family members
  ]
}

Important Notes for Updating Family Information:

  • The family_members array in the request can contain multiple family members.
  • For each family member:
    • If an id is provided, the existing record will be updated.
    • If no id is provided, a new family member record will be created.
  • Fields that can be updated for each family member:
    • relation: The relationship type (e.g., "Brother", "Mother", "Father")
    • name: Full name of the family member
    • number: Contact number of the family member (optional)
    • occupation: Occupation of the family member (optional)
    • address: Residential address of the family member (optional)
  • The pic field cannot be updated through this API endpoint. It's only included in the response.
  • After a successful update, the response includes all family members associated with the member, including any newly created records.
  • The created_at and updated_at timestamps are automatically managed by the system.
  • This endpoint allows for adding, updating, and implicitly removing family members (by not including them in the request).
  • Ensure that the provided church_id and email match an existing member record.

4. Update Profession and Education Information

PUT https://api4mobile.dachurchman.com/api/update-profession-education-info

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "employment_status": "string",
  "education_level": "string",
  "occupation": "string",
  "start_date": "date|null",
  "end_date": "date|null",
  "employment_institution": "string|null",
  "professional_directory": "boolean"
}

Response:

{
  "message": "Profession and Education information updated successfully",
  "member": {
    // Updated member object
  }
}

Important Notes:

  • All endpoints require authentication. The token should be included in the request body.
  • The email and church_id are used to identify the correct member record to update.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • Fields marked as nullable can be omitted or set to null if not applicable.
  • Date fields should be in the format "YYYY-MM-DD".
  • Boolean fields should be sent as true or false.
  • The professional_directory field in the Profession and Education update determines whether the member is listed in the professional directory.
  • If a member is not found for the given email and church_id combination, a 404 error will be returned.
  • Validation errors will return a 422 status code with details about the invalid fields.
  • After a successful update, the relevant updated information is returned in the response.
  • Error responses will include a descriptive message to help diagnose the issue.
  • These endpoints are designed for personal use only. Members can only update their own records.
  • Sensitive information updates should be handled with care and in compliance with data protection regulations.
  • The system may have additional validation or restrictions on certain fields that are not reflected in this API documentation.

Fetch Online Offering Sources

GET https://api4mobile.dachurchman.com/api/online-offering-sources

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string

Response:

{
  "message": "Online offering sources fetched successfully",
  "offering_sources": [
    {
      "id": integer,
      "type": string,
      "source": string,
      "mode": string,
      "distributable_id": integer,
      "account_header": string
    },
    // ... more offering sources
  ]
}

Important Notes:

  • This endpoint retrieves all offering sources where accept_online_payment = 1 for the specified church.
  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the query string for authentication.
  • The email parameter is used to verify the user's association with the specified church.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • If no offering sources are found, an empty array will be returned in the offering_sources field.
  • Error responses will include a descriptive message to help diagnose the issue.
  • The type field indicates the category of the offering source.
  • The source field provides the specific name or description of the offering source.
  • The mode field may indicate the method of collection or other relevant information.
  • The distributable_id is a reference to associated distribution rules, if applicable.
  • The account_header field provides accounting categorization information.

Fetch Member Offering History

GET https://api4mobile.dachurchman.com/api/member-offering-history

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string
page: integer (optional, default: 1)
per_page: integer (optional, default: 10, max: 50)

Response:

{
  "message": "Member offering history fetched successfully",
  "offering_history": [
    {
      "id": integer,
      "amount": decimal,
      "date": "YYYY-MM-DD",
      "source": string,
      "payment_method": string
    },
    // ... more offering entries
  ],
  "current_page": integer,
  "total_pages": integer,
  "total_offerings": integer
}

Important Notes:

  • This endpoint retrieves the offering history for a specific member, identified by their email and church_id.
  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the query string for authentication.
  • The email parameter is used to identify the specific member whose offering history is being requested.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the offering history.
  • If no offerings are found, an empty array will be returned in the offering_history field.
  • The offering entries are sorted by date in descending order (most recent first).
  • The amount field represents the monetary value of the offering.
  • The source field indicates the type or category of the offering.
  • The payment_method field shows how the offering was made (e.g., cash, online, etc.).
  • Error responses will include a descriptive message to help diagnose the issue.
  • This endpoint is designed for personal use only. Members can only view their own offering history.

Fetch Member Welfare Contribution History

GET https://api4mobile.dachurchman.com/api/member-welfare-contribution-history

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string
page: integer (optional, default: 1)
per_page: integer (optional, default: 10, max: 50)

Response:

{
  "message": "Member welfare contribution history fetched successfully",
  "welfare_contributions": [
    {
      "id": integer,
      "amount": decimal,
      "date": "YYYY-MM-DD"
    },
    // ... more contribution entries
  ],
  "current_page": integer,
  "total_pages": integer,
  "total_contributions": integer
}

Important Notes:

  • This endpoint retrieves the welfare contribution history for a specific member, identified by their email and church_id.
  • Only contributions of type 'payment' are included in the response.
  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the query string for authentication.
  • The email parameter is used to identify the specific member whose welfare contribution history is being requested.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the contribution history.
  • If no contributions are found, an empty array will be returned in the welfare_contributions field.
  • The contribution entries are sorted by date in descending order (most recent first).
  • The amount field represents the monetary value of the welfare contribution.
  • Error responses will include a descriptive message to help diagnose the issue.
  • This endpoint is designed for personal use only. Members can only view their own welfare contribution history.

Fetch Member Welfare Benefit History

GET https://api4mobile.dachurchman.com/api/member-welfare-benefit-history

Parameters (Query String):

email: string
church_id: integer
server_url: string
token: string
page: integer (optional, default: 1)
per_page: integer (optional, default: 10, max: 50)

Response:

{
  "message": "Member welfare benefit history fetched successfully",
  "welfare_benefits": [
    {
      "id": integer,
      "amount": decimal,
      "date": "YYYY-MM-DD"
    },
    // ... more benefit entries
  ],
  "current_page": integer,
  "total_pages": integer,
  "total_benefits": integer
}

Important Notes:

  • This endpoint retrieves the welfare benefit history for a specific member, identified by their email and church_id.
  • Only entries of type 'benefit' are included in the response.
  • The token and church_id are provided by the mobile app. These values are obtained during the login process and stored in the app.
  • The token should be included in the query string for authentication.
  • The email parameter is used to identify the specific member whose welfare benefit history is being requested.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • Pagination is supported through the page and per_page parameters. Adjust these to navigate through the benefit history.
  • If no benefits are found, an empty array will be returned in the welfare_benefits field.
  • The benefit entries are sorted by date in descending order (most recent first).
  • The amount field represents the monetary value of the welfare benefit received.
  • Error responses will include a descriptive message to help diagnose the issue.
  • This endpoint is designed for personal use only. Members can only view their own welfare benefit history.

Mobile App Interactions

1. Like Content

POST https://api4mobile.dachurchman.com/api/like

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "content_type": "string (stream|event|devotion|podcast)",
  "content_id": "integer"
}

Response:

{
  "message": "Content liked successfully",
  "like": {
    // Like object details
  },
  "counts": {
    "like_count": integer,
    "share_count": integer,
    "comment_count": integer,
    "prayer_request_count": integer
  }
}

2. Share Content

POST https://api4mobile.dachurchman.com/api/share

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "content_type": "string (stream|event|devotion|podcast)",
  "content_id": "integer"
}

Response:

{
  "message": "Content shared successfully",
  "share": {
    // Share object details
  },
  "counts": {
    "like_count": integer,
    "share_count": integer,
    "comment_count": integer,
    "prayer_request_count": integer
  }
}

3. Add Comment

POST https://api4mobile.dachurchman.com/api/comment

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "content_type": "string (stream|event|devotion|podcast)",
  "content_id": "integer",
  "comment": "string"
}

Response:

{
  "message": "Comment added successfully",
  "comment": {
    // Comment object details
  },
  "counts": {
    "like_count": integer,
    "share_count": integer,
    "comment_count": integer,
    "prayer_request_count": integer
  }
}

4. Add Prayer Request

POST https://api4mobile.dachurchman.com/api/prayer-request

Parameters (JSON):

{
  "email": "string",
  "church_id": "integer",
  "server_url": "string",
  "token": "string",
  "content_type": "string (stream|event|devotion|podcast)",
  "content_id": "integer",
  "prayer_request": "string"
}

Response:

{
  "message": "Prayer request added successfully",
  "prayer_request": {
    // Prayer request object details
  },
  "counts": {
    "like_count": integer,
    "share_count": integer,
    "comment_count": integer,
    "prayer_request_count": integer
  }
}

Important Notes:

  • All endpoints require authentication. The token should be included in the request body.
  • The email and church_id are used to identify the member performing the action.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The content_type parameter should be one of: stream, event, devotion, or podcast.
  • The content_id parameter is the unique identifier of the specific content being interacted with.
  • For comments and prayer requests, additional text content is required in the respective fields.
  • Each response now includes a 'counts' object with the current counts for likes, shares, comments, and prayer requests for the specified content.
  • The counts reflect the total number of interactions for the specific content across all members.
  • Error responses will include a descriptive message to help diagnose the issue.
  • These endpoints are designed for use within the mobile app and should be protected against unauthorized access.
  • The like endpoint will create a new like or update an existing one if the member has already liked the content.
  • The share endpoint creates a new share record each time it's called, allowing multiple shares by the same member.
  • Comments and prayer requests are always created as new entries.

Fetch Available Hymn Languages

GET https://api4mobile.dachurchman.com/api/hymns/languages

Parameters (Query String):

email: string (required)
church_id: integer (required)
server_url: string (required)
token: string (required)

Response:

{
  "message": "Hymn languages fetched successfully",
  "languages": ["English", "Twi", "French", ...]
}

Fetch Hymn List

GET https://api4mobile.dachurchman.com/api/hymns

Parameters (Query String):

email: string (required)
church_id: integer (required)
server_url: string (required)
token: string (required)
language: string (required)
page: integer (optional, default: 1)
per_page: integer (optional, default: 50, max: 100)
filter: string (optional)
filter_type: string (optional, values: number, first_line, tune, meter)

Response:

{
  "message": "Hymn list fetched successfully",
  "hymns": [
    {
      "id": integer,
      "number": integer,
      "first_line": string,
      "tune": string,
      "meter": string,
      "category": string,
      "sub_category": string,
      "optional_sub_category": string,
      "key": string,
      "author": string,
      "amen": string
    }
  ],
  "current_page": integer,
  "total_pages": integer,
  "total_hymns": integer
}

Fetch Hymn Detail

GET https://api4mobile.dachurchman.com/api/hymns/{id}

Parameters (Query String):

email: string (required)
church_id: integer (required)
server_url: string (required)
token: string (required)

Response:

{
  "message": "Hymn detail fetched successfully",
  "hymn": {
    "id": integer,
    "number": integer,
    "first_line": string,
    "tune": string,
    "meter": string,
    "category": string,
    "sub_category": string,
    "optional_sub_category": string,
    "key": string,
    "author": string,
    "stanzas": [
      {
        "number": integer,
        "type": string,
        "content": string
      }
    ],
    "amen": string
  }
}

Important Notes:

  • All endpoints require authentication. The token should be included in the query parameters.
  • The email and church_id are used to identify the user and their associated church.
  • The server_url parameter allows the central API server to forward the request to the appropriate church-specific server.
  • The getLanguages endpoint fetches available languages for hymns based on the user's church denomination.
  • For the hymn list endpoint:
    • The language parameter is required and should be one of the languages returned by the getLanguages endpoint.
    • Hymns are filtered by the denomination of the user's church automatically.
    • Pagination is supported through the page and per_page parameters.
    • Additional filtering is available using the filter and filter_type parameters.
    • Valid filter_type values are: number, first_line, tune, meter.
  • The hymn list endpoint returns basic information for each hymn, including names of related entities instead of IDs.
  • The hymn detail endpoint returns comprehensive information about a single hymn, including all stanzas and names of related entities.
  • The 'amen' field is a string representing the "Amen" at the end of the hymn, if present.
  • Error responses will include a descriptive message to help diagnose the issue.

8. Error Handling

All endpoints follow a consistent error response format:

{
  "error": "Error message describing the issue"
}

Common HTTP status codes:

  • 400: Bad Request - Invalid parameters
  • 401: Unauthorized - Invalid OTP or authentication failure
  • 403: Forbidden - User not authorized for the requested action
  • 404: Not Found - Resource not found (e.g., member or church)
  • 422: Unprocessable Entity - Validation errors
  • 500: Internal Server Error - Unexpected server issues

9. Rate Limiting

To protect our services from abuse, rate limiting is implemented on all endpoints. The current limits are:

  • Login attempts: 5 per minute per IP address
  • OTP verification: 3 per minute per email address
  • Signup initiation: 3 per hour per email address

When a rate limit is exceeded, the API will respond with a 429 (Too Many Requests) status code.

10. Security Considerations

To ensure the security of your application and user data, please adhere to the following guidelines:

  • Always use HTTPS for all API communications
  • Store sensitive data (e.g., OTPs) securely and temporarily
  • Implement proper session management in your mobile application
  • Regularly update your application to include the latest security patches

9. Future Expansions

The following features are planned for future releases:

  • Profile Management
  • Church Events
  • Donations and Payments
  • Messaging System

Detailed documentation for these features will be provided upon release.

10. Support and Contact

For API support, bug reports, or feature requests, please contact our developer support team:

Please include detailed information about your issue or request, including any relevant code snippets or error messages.

DaChurchMan Website
API Documentation v1.0.0