Technical Specification

Specification Details

This web service supports only restful requests.

Methods

Ping

This method is called to confirm the availability of the service.

1. URL

Request URL - http://ADVISED-IP/simswap-central/api/ping

Request Method - GET

2. Sample Response

{
   "responseCode":"00",
   "responseDescription":"“SIM SWAP SERVICE RUNNING"


}

Reset

This method is called to generate credentials for the encryption of request messages in subsequent API calls. A secret key is generated. This method should only be called on credential change.

1. URL

Request URL - http://ADVISED-IP/simswap-central/api/reset

Request Method – POST

2. Sample JSON Request and Response

Request

{
    "username":"clientusername"
}

Response

{
   "status":"00",
   "message”:” RESET SUCCESSFUL.USE THE NEW CREDENTIALS SUBSEQUENTLY.”,
   “otherInfo”:”sDER!^845045”


}

Login

This method leverages on JWT (Json Web Tokens API) to validate the client username and the generated encryption credentials and upon successful validation, returns an authorization string which the client will pass in header of subsequent request. This guarantees system to system access for a configured period of time(in seconds, minutes, hours, days, months, years etc) after which the token expires.

Request URL: - http://ADVISED-IP/simswap-central/api/login

Request Method: POST

4.3.2 Sample JSON Request and Response

{
   "username":"clientusername",
   "secretKey":" 6426ya70-f4ba-43c3-9f"
}

If the http status code is 200, check the header string for the value of the parameter "Authorization" which will contain a value similar to the string highlighted in yellow below:

CLIENTXXX (Please use the tab button to create a space) eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJJTlRFR1JBVE9SIiwiaXNzIjoiaHR0cDovLzEyNy4w LjAuMTo4MDgwLzJGQVNlcnZpY2UvYXBpL2F1dGgvbG9naW4iLCJpYXQiOjE1MDY wNzI5MzksImV4cCI6MTUwNjE1OTMzOX0.0Nas5e2137dsmw77_Gil7jHfsqr_3Wx4BX TnMpkIb24TGrm1pSL1F5xlZztcYR3qJCwS4sjH41B-9_vlOqopAA

You are required to pass this generated string in the "Authorization" parameter on subsequent requests. An example shown is shown below

Authorization :

CLIENTXXX

eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJJTlRFR1JBVE9SIiwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MDgwLzJGQVNlcnZpY2UvYXBpL2F1dGgvbG9naW4iLCJpYXQiOjE1MDYwNzI5MzksImV4cCI6MTUwNjE1OTMzOX0.0Nas5e2137dsmw77_Gil7jHfsqr_3Wx4BXTnMpkIb24TGrm1pSL1F5xlZztcYR3qJCwS4sjH41B-9_vlOqopAA

Note: Where XXX is the client API username.

For example, if your username is APP, your authorization string will start with "CLIENTAPP"

Get Sim Swap Status

This method gets the SIM swap status of a particular mobile subscriber

1 Sample JSON Request and Response

POST http://ADVISED-IP/simswap-central/api/status/

Request Body

Name	Type	Description
clientCode	number
requestID	number
telco	string
phoneNumber	number

200

{
    "clientCode":"999044",
    "requestID":"99904400000000000001",
    "telco":"MTN",
    "phoneNumber":"2348099999999”,
    "responseCode":"00",
    "responseDescription":"Success",
    “simSwapMode”:”SWAPPED”,
    “simSwapDate”:”2017-09-03 15:12:25”
}

Request

{
    "clientCode":"999044",
    "requestID":"99904400000000000001",
    "telco":"MTN",
    "phoneNumber":"2348099999999”
}

Encrypted Request:

044acb780cec00ae106a4b31b85f9674d41aa808f887d8a1b70c30053d8de4a5873d9bd731dffa8a26cb344e4f73b1825f35cb0a052126b042746b34d2b2e599f9445d