Chapter 2

Member verification

Member API

The Member API provides endpoints for managing member information.

GET MEMBER CARD DETAILS

  • Endpoint: GET /v1/members/{card_no}
  • Description: Retrieves card details for a specific member.

URL Parameters:

Parameter Type Description
card_no string The member's card number.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X GET \
    'https://your-api-domain/v1/members/123456789' \
    -H 'Authorization: Bearer <YOUR_TOKEN>'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Card details retrieved successfully"
    ],
    "data": {
      "card_no": "123456789",
      "name": "John Doe",
      "gender": "Male",
      "dob": "1990-01-15"
    }
  }

Example Error Response (404 Not Found):

  {
    "success": false,
    "statusCode": 404,
    "message": [
      "No record found"
    ],
    "data": null
  }

GET MEMBER CARD BENEFITS

  • Endpoint: GET /v1/members/benefit/{card_no}
  • Description: Retrieves policy benefits for a member.

URL Parameters:

Parameter Type Description
card_no string The member's card number.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X GET \
    'https://your-api-domain/v1/members/benefit/123456789' \
    -H 'Authorization: Bearer <YOUR_TOKEN>'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Benefits retrieved successfully"
    ],
    "data": [
        {
            "code": "OPD",
            "name": "Out-Patient Services",
            "access_type": "Referral"
        },
        {
            "code": "IPD",
            "name": "In-Patient Services",
            "access_type": "Direct"
        }
    ]
  }

Example Error Response (404 Not Found):

  {
    "success": false,
    "statusCode": 404,
    "message": [
      "No record found"
    ],
    "data": null
  }

GENERATE VISIT

  • Endpoint: POST /v1/members/visit
  • Description: Verifies a member's eligibility for a specific benefit at a provider and sends an OTP if successful.

Request Body:

Parameter Type Required Description
card_no string Yes The member's card number.
policy_benefit_code string Yes The code for the policy benefit.
phone string Yes The member's phone number.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X POST \
    'https://your-api-domain/v1/members/visit' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
          "card_no": "123456789",
          "policy_benefit_code": "OPD",
          "phone": "+255768983899"
      }'

Example Success Response (200 OK):

{
    "success": true,
    "statusCode": 200,
    "message": [
      "OTP code for treatment was sent to JOHN DOE via SMS to number +255768****99"
    ],
    "data": {
      "otp_expire_at": "2025-07-14 14:25:00",
      "visit_request_id" : "123"
    }
  }

Example Error Response (422 Unprocessable Entry):

  {
    "success": false,
    "statusCode": 422,
    "message": [
      "Member has a pending visit request"
    ],
    "data":  { 
      "visit_request_id" : "123"
    }
  }

GENERATE AUTHORIZATION NO.

  • Endpoint: POST /v1/members/verification
  • Description: Confirms a member's visit by validating the OTP and generates an authorization number.

Request Body:

Parameter Type Required Description
card_no string Yes The member's card number.
policy_benefit_code string Yes The code for the policy benefit.
otp_code string Yes The OTP code sent to the member.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X POST \
    'https://your-api-domain/v1/members/verification' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
          "card_no": "123456789",
          "policy_benefit_code": "OPD",
          "otp_code": "123456"
      }'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
        "ACCEPTED"
    ],
    "data": {
        "authorization_no": "ATI-2025-000001"
    }
}

Example Error Response (422 Unprocessable Entry):

  {
    "success": false,
    "statusCode": 422,
    "message": [
        "Invalid or Expired OTP"
    ],
    "data": null
}

GET VISIT DETAILS

  • Endpoint: | GET /v1/members/visit/{visit_request_id}
  • Description: Get visit request details by using visit request id.

URL Parameters:

Parameter Type Description
visit_request_id string The visit request id.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X GET \
    'https://your-api-domain/v1/members/visit/1122' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Successful retrieved visit request"
    ],
    "data": {
        "card_no": "123456789",
        "policy_benefit_code": "OPD",
        "status": "APPROVED",
        "authorization_number": "ATI-2025-000001"
    }
  }

Example Error Response (404 No record found):

  {
    "success": false,
    "statusCode": 404,
    "message": [
      "No record found"
    ],
    "data": null
  }

GET AUTHORIZATION DETAILS

  • Endpoint: | GET /v1/members/authorization/{authorization_no}
  • Description: Get authorization details by using authorization number.

URL Parameters:

Parameter Type Description
authorization_no string The authorization number.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X GET \
    'https://your-api-domain/v1/members/authorization/1122' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Successful retrieved authorization"
    ],
    "data": {
        "card_no": "123456789",
        "policy_benefit_code": "OPD",
        "status": "APPROVED",
        "authorization_number": "ATI-2025-000001"
    }
  }

Example Error Response (404 No record found):

  {
    "success": false,
    "statusCode": 404,
    "message": [
      "No record found"
    ],
    "data": null
  }

BLOCK MEMBER BENEFIT AFTER SERVICE

  • Endpoint: POST /v1/members/benefit/block
  • Description: Blocks a certain amount from a member's benefit after a service has been rendered.

URL Parameters:

Parameter Type Description

Request Body:

Parameter Type Required Description
card_no string Yes The member's card number.
amount numeric Yes The amount to block from the benefit.
authorization_no string Yes The authorization number from the confirm step.

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X POST \
    'https://your-api-domain/v1/members/benefit/block' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
          "card_no": "123456789",
          "amount": 5000,
          "authorization_no": "ATI-2025-000001"
      }'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Benefit blocked successfully"
    ],
    "data": {
      "benefit": "OPD",
        "requested_amount": "10000.00",
        "covered_amount": "10000.00"
    }
  }

Example Error Response (422 Unprocessable Entry):

  {
    "success": false,
    "statusCode": 422,
    "message": [
      "Invalid authorization number"
    ],
    "data": null
  }

GET VISIT BLOCKED BENEFIT

  • Endpoint: GET /v1/members/benefit/block/{authorization_no}
  • Description: Get visit blocked benefit using authorization number.

URL Parameters:

Parameter Type Description
authorization_no string The authorization number.

Request Body:

Parameter Type Required Description

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X GET \
    'https://your-api-domain/v1/members/benefit/block/ATI-2025-000001' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Benefit blocked"
    ],
    "data": {
      "id": "35185",
        "authorization_no": "ATI0078",
        "covered_amount": "40000.0000",
        "benefit": "OPD"
    }
  }

Example Error Response (422 Unprocessable Entry):

  {
    "success": false,
    "statusCode": 422,
    "message": [
      "Invalid authorization number"
    ],
    "data": null
  }

GET MEMBER PHOTO

  • Endpoint: GET /v1/members/photo/{card_no}
  • Description: Get member photo using card no.

URL Parameters:

Parameter Type Description
card_no string The card number.

Request Body:

Parameter Type Required Description

Headers:

Header Value
Authorization Bearer <TOKEN>

Example Request:

  curl -X GET \
    'https://your-api-domain/v1/members/photo/123456789' \
    -H 'Authorization: Bearer <YOUR_TOKEN>' \
    -H 'Content-Type: application/json'

Example Success Response (200 OK):

  {
    "success": true,
    "statusCode": 200,
    "message": [
      "Member Photo"
    ],
    "data": {
      "photo": "data:image\/jpg;base64,\/9j\/4AAQSkZJRgABAQEAyADIAAD\/4QNyRXhpZgAATU0AKgAAAAgACAEPAAIAAAADSFAABAEQAAIAAAAQAAAAbgEaAAUAAAABAA..............."
    }
  }

Example Error Response (422 Unprocessable Entry):

  {
    "success": false,
    "statusCode": 422,
    "message": [
      "Invalid card number"
    ],
    "data": null
  }