> For the complete documentation index, see [llms.txt](https://testdocs.nibss-plc.com.ng/simswap/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://testdocs.nibss-plc.com.ng/simswap/technical-specification.md).

# 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](http://advised-ip/simswap-central/api/ping)

Request Method - GET

**2. Sample Response**

```javascript
{
   "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](http://advised-ip/simswap-central/api/reset)

 Request Method – POST

**2**.  **Sample JSON Request and Response**

{% tabs %}
{% tab title="Request" %}

```javascript
{
    "username":"clientusername"
}
```

{% endtab %}

{% tab title="Response" %}

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


}
```

{% endtab %}
{% endtabs %}

### **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](http://advised-ip/simswap-central/api/login)

**Request Method**: POST

**4.3.2** **Sample JSON Request and Response**

```javascript
{
   "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:

CLIENT**XXX** *(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** :

CLIENT**XXX**

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**

<mark style="color:green;">`POST`</mark> `http://ADVISED-IP/simswap-central/api/status/`

#### Request Body

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| clientCode  | number |             |
| requestID   | number |             |
| telco       | string |             |
| phoneNumber | number |             |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}
{% endtabs %}

**Encrypted Request**:

```markup
044acb780cec00ae106a4b31b85f9674d41aa808f887d8a1b70c30053d8de4a5873d9bd731dffa8a26cb344e4f73b1825f35cb0a052126b042746b34d2b2e599f9445d
```