Login and registration

Every pin field on this page is the 4-digit PIN as the shipped apps send it: encrypted by the app (see the overview). Verification codes are 4 digits, sent by SMS from the church's sender ID, valid for 5 minutes and usable once. Codes are rate limited per phone number (rate limits).

Typical flow

1. POST login-phone with the phone: the churches this number belongs to.
2. The member picks a church; POST login/{church} with phone and PIN returns the member token.
3. Optionally POST send-login-otp/{church} then POST verify-otp/{church} when the church requires a login code.
4. A new member registers with POST register-member/{church} (sends a code) then POST confirm-otp/{church} (creates the account).

Churches for a phone number

curl -X POST https://uat-api.mychurch.co.ke/api/v2/login-phone \
  -H "Content-Type: application/json" \
  -d '{"phone": "0712345678"}'

{
  "message": "Success",
  "status": true,
  "churches": [
    { "uuid": "00000000-0000-4000-8000-000000000001", "church_name": "Grace Community Church" }
  ]
}

A number with no membership anywhere answers {"message": "You are not registered to any church", "status": false}. Churches hidden from the app are left out of the list.

Log in

curl -X POST https://uat-api.mychurch.co.ke/api/v2/login/00000000-0000-4000-8000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{"phone": "254712345678", "pin": "<encrypted pin>"}'

{
  "message": "Login successful",
  "status": true,
  "token": "11111111-2222-4333-8444-555555555555",
  "photo": "https://uat-api.mychurch.co.ke/storage/scarlet/profiles/jane.jpg",
  "account": {
    "first_name": "Jane",
    "middle_name": "",
    "other_names": "Wanjiku",
    "primary_phone": "254712345678",
    "alternative_phone": null,
    "email": "[email protected]",
    "physical_address": "Kilimani, Nairobi",
    "date_of_birth": "1990-04-12",
    "confirmation_date": null,
    "married_on": null,
    "age_group": {
      "id": 3, "uuid": "00000000-0000-4000-8000-0000000000a3", "church_id": 12,
      "name": "Adults", "from_age": 26, "to_age": 60,
      "deleted_at": null, "created_at": "2024-01-10T07:00:00.000000Z", "updated_at": "2024-01-10T07:00:00.000000Z"
    },
    "status": 1,
    "gender": 2,
    "marital_status": 2,
    "uuid": "00000000-0000-4000-8000-0000000000b1",
    "member_number": "GC042",
    "tithe_number": null,
    "blocked": null,
    "department_name": "Departments",
    "cell_group_name": "Cell Groups"
  }
}

status in account is 0 pending, 1 active, 3 inactive. blocked is the opt-out record when the member has stopped non-transactional SMS, else null. department_name and cell_group_name are the church's own words for those groups, for the app's labels. Failures (all HTTP 200, status: false):

• You are not a registered member of Grace Community Church
• Your Grace Community Church membership has not been approved. Contact the church administrator for more info: 0700000000
• Invalid credentials (with "token": null)
• An error occurred when the PIN does not decrypt

On /api/v1/login/{church} the response carries token, photo and name instead of the account block.

Login OTP (optional second step)

Some churches require a code after the PIN. The app calls send-login-otp with the token it just received and reads status_int.

No body. Answers, all status: true:

• status_int: 1, Otp has been sent to your phone: ask for the code.
• status_int: 2, Otp login not allowed: the church does not use login codes; continue.
• status_int: 3, Success: the church remembers logins; continue.

{
  "message": "Login successful",
  "status": true,
  "token": "11111111-2222-4333-8444-666666666666",
  "photo": null,
  "name": "Jane Wanjiku"
}

A new token is issued; use it from now on. A wrong code answers Your have entered the wrong otp (the spelling is what the apps match on).

Register a new member

1. Send the verification code

{"message": "A verification code has been sent to your phone", "status": true}

Failures: You are already registered to this church, Member should be 18yrs and above, Invalid date, Registration could not be completed. Please try again later. An invalid phone is a 422 with "0712 is invalid" as the message.

2. Confirm the code and create the account

Send the same fields again, plus:

{"message": "Your account is being created. You will receive an sms shortly", "status": true}

The account exists when this answers. It is active, or pending when the church approves new members first (login then answers with the not-approved message). Pledges and children recorded earlier against this phone are linked to the new member, and the church's welcome SMS is sent. A wrong code answers Your have entered the wrong verification code. The member logs in next with login/{church}.

Age groups for the registration form

{
  "message": "success",
  "status": true,
  "age_groups": [
    { "uuid": "00000000-0000-4000-8000-0000000000a1", "name": "Youth", "group": "18-25" },
    { "uuid": "00000000-0000-4000-8000-0000000000a3", "name": "Adults", "group": "26-60" }
  ]
}

Forgot PIN

1. Send a code

{"message": "A verification code has been sent to your phone", "status": true}

Unknown number: You are not registered to this church.

2. Verify the code

{"message": "Request successful", "status": true, "token": "11111111-2222-4333-8444-777777777777"}

The token authorises step 3. Wrong code: You have entered the wrong verification code.

3. Set the new PIN

{"message": "Your pin has been changed", "status": true}

Change PIN and log out

{"message": "Your pin has been changed", "status": true}

Wrong current PIN: You have entered a wrong current password.

{"message": "You have logged out", "status": true}