Guide: Captive User Account Bulk Upload & Top-Ups API

Captive User Accounts Bulk Upload and Add Top-Ups through API

Overview

The Bulk Upload API allows you to create or update multiple Captive user accounts in a single API request. It supports setting user details, assigning data plans, controlling login access, applying site-level restrictions (in v3) and applying access network-level restrictions (in v4).

The Top-Up API allows you to add top-up quotas to multiple Captive user accounts in a single API request.

The List Organizations API retrieves information about the organization and all sub-organizations under it. This enables the user to know the required "dpIds" to perform the Bulk Upload & Top-Up API operations.

Note – These APIs can be used to integrate Sat-Elite Captive Portal with the Crew Welfare Systems available with you or similar systems.

1. API Key

You will need the correct API key for the Distribution Partner (DP) or Organization under which users are being managed. Please procure them from the Sat-Elite Support team.

Each request must include:

auth-key: <your-production-auth-key>

Content-Type: application/json

2. Know the Distribution Partner Identification Numbers (DPIDs)

Purpose

Similar to auth keys, "dpIds" are necessary to perform API operations in the correct organization. The "dpIds" can be obtained by using the List organization API. Users can find it under the Production section in http://readme.io .

The List Organizations API retrieves information about the organization and all sub-organizations under it.

Endpoint

Method: GET

URL: https://api.kognitive.net/ext/v1/organizations

Each request must include:

auth-key: <your-production-auth-key>

Content-Type: application/json

Steps to Use

• Obtain your Production API key from the Sat-Elite Support team.

• Choose a tool: http://Readme.io , Postman, curl, etc.

• Set request headers with your API key and JSON accept header.

• Set optional query parameter "orgId" if needed.

• Send the GET request to the endpoint.

• Check the response for a list of organizations and their sub-organizations.

Sample Response

{

  "organization": {

    "id": "DP-0121",

    "name": "Main Organization",

    "subOrganizations": [

      {

        "id": "DP-0122",

        "name": "Sub Organization 1"

      },

      {

        "id": "DP-0123",

        "name": "Sub Organization 2"

      }

    ]

  }

}

3. Bulk Upload API v2

Purpose

This allows you to create or update multiple user accounts in a single API call. This version supports assigning users to predefined data plans and setting attributes such as login access, anonymity, and user remarks.

Endpoint

Method: POST

URL: https://api.k4mobility.com/captive/all/user/v2/importUsersV2

Payload Structure

{

  "userData": [

    {

      "action": "add",

      "username": "newuser1",

      "email": "newuser1@mail.com",

      "password": "password123",

      "planName": "Monthly 50GB",

      "loginAccess": false,

      "remark": "Add new account",

      "anonymous": false

    },

    {

      "action": "update",

      "username": " testuser9970",

      "loginAccess": true,

      "remark": "Grant login access",

      "anonymous": false

    }

  ],

  "dpIds": [

    "DP-0308"

  ],

  "admin_name": "admin.email@domain.com"

}

Notes

• "action" can be "add" (create new user) or "update" (modify existing).

• "username" is mandatory for any action.

• The user can set the password using the "password" tag.

• "planName" must match a valid plan in the system.

• "loginAccess" can be used to enable/disable the user accounts.

• "dpIds" are unique identifiers for the Distribution Partners.

• "admin_name" identifies who performed the bulk action.

4. Bulk Upload API v3 (With Site Restrictions)

Purpose

The Bulk Upload API v3 extends the functionality of v2 by introducing site-level restrictions, allowing admins to control which sites a user can access.

Endpoint

Method: POST

URL: https://api.k4mobility.com/captive/all/user/v3/importUsersV2

Payload Structure

{

  "userData": [

    {

      "action": "add",

      "username": "siteuser1",

      "email": "siteuser1@mail.com",

      "password": "abcdef123",

      "planName": "Monthly 50GB",

      "loginAccess": false,

      "allowedSites": "MY-Site01, MY-Site02",

      "remark": "Restricted account",

      "anonymous": false

    },

    {

      "action": "update",

      "username": "siteuser2",

      "loginAccess": true,

      "remark": "Enable login",

      "anonymous": false

    }

  ],

  "dpIds": [

    "DP-0111"

  ],

  "admin_name": "admin.email@domain.com"

}

Notes

• "allowedSites" accepts a comma-separated list of site names.

• If "allowedSites" is not provided, the behavior depends on the action:

  • If the "action" is 'add', the user can log in from any site within the organization.

  • If the "action" is 'update', the user’s existing site permissions remain unchanged.

5. Bulk Upload API v4 (With Access Networks restrictions)

Purpose

The Bulk Upload API v3 extends the functionality of v2 by introducing Access networks-level restrictions, allowing admins to control which access networks a user can use.

Endpoint

Method: POST

URL: https://api.k4mobility.com/captive/all/user/v4/importUsersV2

Payload Structure

{

    "dpIds":["DP-0308"],

    "userData": [

{

"action": "add",

"username": "testuser9968",

"email": "test.auto@mailinator.com ",

"password": "abcdef123",

"planName": "Monthly 50GB",

"loginAccess": false,

"allowedSites": "MY-DemoSite01, MY-DemoSite02",

"remark": "Add an account.",

"anonymous": false

},

{

"action": "add",

"username": "testuser9969",

"email": "testuser9968@mailinator.com ",

"loginAccess": false, 

"allowedSites": "MY-DemoSite02",

"allowedAccessNetworks":["default","crew"]

"remark": "Add an account.",

"anonymous": false

},

{

"action": "update",

"username": "testuser9970",

"loginAccess": true,

"remark": "Remove login access",

"anonymous": false

}

],

    "admin_name":"testadmin@gmail.com"

}

Sample Response - Success

{

    "status": 1,

    "msg": "Users information updated"

}

6. Top-Up

Purpose

This allows you to add top-up quotas to multiple user accounts in a single API call.

Endpoint

Method: POST

URL: https://api.k4mobility.com/captive/all/user/v1/addTopupBulk

Payload Structure

{

    "dpIds":["DP-0252"],

    "userData":[

        {"username":"testuser","topupQuota":50000000}

    ],

    "admin_name":" admin.email@domain.com "

}

Sample Response - Success

{

    "status": 1,

   "msg": "Updated 1 user of 1 users"

}

Payload Structure

{

"dpIds":["DP-0252"],

"userData":[

{"username":"demotest@gmail.com","topupQuota":500000000},

{"username":"testuser2","topupQuota":50000000}

],

"admin_name":" admin.email@domain.com "

}

Sample Response – Failure

{

"status": 1,

"msg": "Updated 0 user of 2 users ,User not found with username -

demotest@gmail.com ,Active Plan not found for user - testuser2"

}

Notes

• "username" should be a string value.

• "topupQuota" should be a number. The volume is given in bytes.

7. Best Practices

• Always double-check the auth-key and dpIds to ensure users are assigned to the correct distribution partner.

• Use unique usernames and emails when adding new accounts.

• Keep passwords secure—avoid reusing test credentials.

• For updates, only include the fields you want changed (other attributes remain as they are).

With this process, you can directly create or update user accounts and add top-ups in the live production environment using API calls. The Top-Up and Update user operations take effect immediately. The adding new user operation takes effect on the next user login.

8. Troubleshooting