LOGIN TO UMS PORTAL

Introduction Last updated: April 23, 2023

This documentation is to help you to regard each step of accessing our information. Please go through the documentation carefully to understand how our web service works. Basic JSON and HTTP knowledge is required to simulate or integrate the API.

To get started with our api intergration you need to have an Api Key, to get an Api Key login into your UMS Portal then click Settings then click api on the menu.If you dont see your api key please click generate then you Api key will apper there.Your api key is as shown bellow.


VE5MTlkzRk06MTlwNjlkZWM=

GET CODE ON GITHUB

Sms

Umeskia softwatres portal Sms offers you an api endpoint that you can quickly pluck your wonderful existing system into our bulk sms platform and seamlessly send bulk sms to your clients with less hustle.

SEND SMS
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/sms
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your UMS Portal VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into UMS Portal example@example.com
Sender_Id Use an active sender id if dont have you can use a default sender id of UMS_SMS company_name or UMS_SMS(default)
message Write the message you want to send here Welcome to my company
phone add the phone number that you are going to send the message to. 0768XXXX090 

                                  {
                                    "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                    "email":"example@gmail.com",
                                    "Sender_Id": "UMS_SMS",
                                    "message": "UMS SMS Api Test Message",
                                    "phone":"0798765432"
                                  }
Response:

                                    {
                                        "success": "200",
                                        "massage": "Message sent sucessfully.",
                                        "request_id": "8403414672158573510"
                                    }
SMS CREDIT BALANCE
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/smsbalance
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your UMS Portal VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into UMS Portal example@example.com 

                                  {
                                    "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                    "email":"example@gmail.com",
                                  }
Response:

                                    {
                                        "success": "200",
                                        "creditBalance": 100,
                                    }
SMS DELIVERY REPORT
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/smsdelivery
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your Umeskia Softwares Portal (USP) VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into Umeskia Software Portal (USP) example@gmail.com
request_id You get the request_id id after every sms is successfully 8403414672158573510 

                                    {
                                        "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                        "email":"example@gmail.com",
                                        "request_id" : "8403414672158573510"
                                      }
Response:

                                  {
                                      "ResultCode": "200",
                                      "request_id": "8403414672158573510",
                                      "submitted_time": "2024-01-26 11:30:40",
                                      "send_time": "2024-01-26 11:30:40",
                                      "sender_id": "UMS_SMS",
                                      "recepient": "0798765432",
                                      "sms_unit": 1,
                                      "sms_length": 150,
                                      "sms_type": "text",
                                      "message":"Welcome to my company STOP *456*9*5#",
                                      "status": "Pending"
                                  }

UMS Pay

UMS Pay is a service that enables you to collect payments on your website or mobile app through M-Pesa STK Push. The money is automatically sent to your M-Pesa till number, paybill number or bank account that you have connect to your UMS Pay account.

INTIATE STK PUSH
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/intiatestk
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your UMS Portal VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into UMS Portal example@example.com
account_id Account id obtained from your UMS Portal UMPAY123456789
amount Amount to request from your customer in KES 1
msisdn Phone number to request money from 254798765432 OR 0798765432
reference (optional) A unique reference that will be used to identify the transaction 675432 

                                    {
                                        "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                        "email":"example@gmail.com",
                                        "account_id":"UMPAY123456789",
                                        "amount" : "10",
                                        "msisdn" : "254798765432",
                                        "reference" : "675432"
                                    }
Response:

                                    {
                                        "success": "200",
                                        "massage": "Request sent sucessfully.",
                                        "tranasaction_request_id": "UMSPID220520232332037855",
                                    }
Success dump:

                                    {
                                        "ResponseCode": 0,
                                        "ResponseDescription": "Success. Request accepted for processing",
                                        "MerchantRequestID": "45695-1488133-1",
                                        "CheckoutRequestID": "ws_CO_220520232332037855",
                                        "TransactionID": "UMSPID220520232332037855",
                                        "TransactionAmount": 1,
                                        "TransactionReceipt": "QBI3DNNHWP",
                                        "TransactionDate": "20210421114425",
                                        "TransactionReference": "675432",
                                        "Msisdn": "254798765432"
                                    }
Error dump:

                                    {
                                        "ResponseCode": 1031,
                                        "ResponseDescription": "Request cancelled by user",
                                        "MerchantRequestID": "45695-1488133-1",
                                        "CheckoutRequestID": "ws_CO_220520232332037855",
                                        "TransactionID": "UMSPID220520232332037855",
                                        "TransactionAmount": 1,
                                        "TransactionReference": "675432",
                                        "Msisdn": "254798765432"
                                    }
Error ResponseCode
ResponseCode ResponseDescription
0 Success. Request accepted for processing
1 The balance is insufficient for the transaction.
1032 Request cancelled by user
1037 DS timeout user cannot be reached
1025 An error occurred while sending a push request
9999 An error occurred while sending a push request.
2001 The initiator information is invalid.
1019 ransaction has expired
1001 Unable to lock subscriber, a transaction is already in process for the current subscriber
TRANSACTION STATUS
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/transactionstatus
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your UMS Portal VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into UMS Portal example@gmail.com
tranasaction_request_id Transaction id that you get after intiating stk push UMSPID220520232332037855 

                                    {
                                        "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                        "email":"example@gmail.com",
                                        "tranasaction_request_id " : "UMSPID220520232332037855"
                                    }
Response:

                                 {
                                      "ResultCode": "200",
                                      "ResultDesc": "Success. Request accepted for processing",
                                      "TransactionID": "UMSPID220520232332037855",
                                      "TransactionStatus": "Completed",
                                      "TransactionCode": "0",
                                      "TransactionReceipt": "SAQ34ZOVL3",
                                      "TransactionAmount": "10",
                                      "Msisdn": "254798765432",
                                      "TransactionDate": "20240126103722",
                                      "TransactionReference": "U77434129"
                                  }

ISP BILLING API

Umeskia Softwares ISP Billing API is a RESTful API that allows you to integrate your ISP billing system with Umeskia Softwares ISP Billing System. The API allows you to get hotspot plans, register vouchers and get vouchers.

GET HOTSPOT PLANS
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/isp/hostspotplans
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your Umeskia Softwares Portal (USP) VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into Umeskia Software Portal (USP) example@gmail.com
station_id Station id from ISP UMS PORTAL UMS26595527 

                                    {
                                        "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                        "email":"example@gmail.com",
                                        "station_id" : "UMS26595527"
                                      }
Response:

                           {
                                        "ResultCode": "200",
                                        "message": "Request sent successfully. UMS26595527",
                                        "ComapanyName": "UMESKIA SOFTWARES",
                                        "CompanyInfo": {
                                            "Address": "Nairobi, Kenya",
                                            "Contact": {
                                                "Email": "info@umeskiasoftwares.com",
                                                "Phone": "0113015674"
                                            },
                                            "Logo": "https://portal.umeskiasoftwares.com/companylogo/1708984865laraAdminfy_logo.png",
                                            "Description": "SOLVING PROBLEMS WITH THE POWER OF TECHNOLOGY.",
                                            "Website": "www.umeskiasoftwares.com",
                                            "primaryColor": "#420505",
                                            "secondaryColor": "#0c2b03"
                                        },
                                        "stationData": {
                                            "stationName": "TANDAO HOTSPOT - KANGU",
                                            "stationLocation": "Kutus, Kenya",
                                            "stationPool": "TANDAO-KANGU-POOL",
                                            "remoteIp": "192.168.74.1",
                                            "nasPassword": "273641958",
                                            "localIp": "192.146.98.1",
                                            "domainName": "ums.net",
                                            "stationId": "UMS26595527",
                                            "customerCare": "0113015674",
                                            "stationPackages": [
                                                {
                                                    "planCode": "U77434129",
                                                    "price": "10",
                                                    "numericExpiration": "5",
                                                    "stringExpiration": " Mbps",
                                                    "planType": "speed",
                                                    "connectionType": "Speed plan",
                                                    "validityPeriod": "1 Hour",
                                                    "allowedDevices": "1"
                                                },
                                                {
                                                    "planCode": "U69568596",
                                                    "price": "10",
                                                    "numericExpiration": "30",
                                                    "stringExpiration": " Minutes",
                                                    "planType": "time",
                                                    "connectionType": "Time plan",
                                                    "validityPeriod": "30 Minutes",
                                                    "allowedDevices": "2"
                                                },
                                                {
                                                    "planCode": "U46169734",
                                                    "price": "10",
                                                    "numericExpiration": "10",
                                                    "stringExpiration": " MB",
                                                    "planType": "data",
                                                    "connectionType": "Data plan",
                                                    "validityPeriod": "1 Hour",
                                                    "allowedDevices": "1"
                                                },
                                                {
                                                    "planCode": "U54849986",
                                                    "price": "20",
                                                    "numericExpiration": "15",
                                                    "stringExpiration": " Hours",
                                                    "planType": "time",
                                                    "connectionType": "Time plan",
                                                    "validityPeriod": "15 Hours",
                                                    "allowedDevices": "2"
                                                },
                                                {
                                                    "planCode": "U92191578",
                                                    "price": "35",
                                                    "numericExpiration": "24",
                                                    "stringExpiration": " Hours",
                                                    "planType": "time",
                                                    "connectionType": "Time plan",
                                                    "validityPeriod": "24 Hours",
                                                    "allowedDevices": "2"
                                                },
                                                {
                                                    "planCode": "U42514542",
                                                    "price": "200",
                                                    "numericExpiration": "1",
                                                    "stringExpiration": " Week",
                                                    "planType": "time",
                                                    "connectionType": "Time plan",
                                                    "validityPeriod": "1 Week",
                                                    "allowedDevices": "2"
                                                }
                                            ]
                                        }
                         }
                                '
REGISTER VOUCHER
Method Endpoint
POST https://api.umeskiasoftwares.com/api/v1/isp/registervoucher
Headers:
Header Description value
Content-Type The Accept request HTTP header advertises which content types, expressed as MIME types, the client can understand. application/json 

                                  "Content-Type : application/json"
Parameters:
Parameter Description Sample value
api_key API key obtained from your Umeskia Softwares Portal (USP) VE5MTlkzRk06MTlwNjlkZWM=
email Email that you use to login into Umeskia Software Portal (USP)
plan_code Plan code from ISP UMS PORTAL U77434129
voucher_code Voucher code from ISP UMS PORTAL GHOT 

                                     {
                                        "api_key":"VE5MTlkzRk06MTlwNjlkZWM=",
                                        "email":"example@gmail.com",
                                        "plan_code" : "U77434129",
                                        "voucher_code" : "GHOT"
                                      }
Response:

                                    {
                                          "ResultCode": "200",
                                          "message": "Voucher registered successfully",
                                          "registeredVoucher": "GHOT",
                                          "stationId": "UMS26595527",
                                          "stationName": "TANDAO HOTSPOT",
                                          "stationLocation": "Chonjo Village, Mwembe Tayari, Mombasa, Kenya",
                                          "planCode": "U77434129",
                                          "planName": "1 HOUR ",
                                          "planPrice": 10
                                      }

Webhook

Webhooks are user-defined HTTP callbacks. They are usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When that event occurs, the source site makes an HTTP request to the URI configured for the webhook. Users can configure them to cause events on one site to invoke behavior on another. The action taken may be anything. Common uses are to trigger builds with continuous integration systems or to notify bug tracking systems.

HOW TO ADD A WEBHOOK Not for Ums Pay
1. Login into your UMS Portal Account
2. Click Settings
3. Go to Api Section
3. Click add Webhook
4. Choose product
5. Add Callback
6. Click Save


HOW TO ADD A WEBHOOK FOR UMS PAY
1. Login into your UMS Portal Account
2. Go the UMS Pay Section
3. Click Webhooks
4. Click add Webhook
5. Choose Accout to add webhook
6. Add Callback Url
7. Click Save