Bharti Airtel Device & Session Information API

openapi: 3.2.0
info:
  version: '1.0'
  title: Airtel IoT Device & Session Information API
  contact:
    email: m2m.support@airtel.com
  description: "# Overview\n ## Introduction\n <div class=\"iot-intro\">Airtel IoT Developer Portal showcases APIs that allows you\n to access data of the CMP Billable account from any external application. Using the APIs, you\n can perform almost all the operations that you perform through the CMP portal including Managing\n SIM Inventory, Changing SIM state (Test Mode, Activate, Change Plan, Safe custody), Monitoring\n data usage, Performing bulk operations and so on.</div>\n                     \n In this section, you’ll learn Airtel IoT Developer Portal Dashboard.\n\n   ## API Credentials\n   This section provide static details of Customer which will be used for accessing APIs.\n\n \n   <div class=\"bullet-list\">  Key Authentication   </div>\n    <div class=\"bullet-list-content\" > A Unique Identification Secret Key per Customer, must be passed in Headers while calling API and will be used for Authentication purpose.</div>\n   \n\n   <div class=\"bullet-list\" > Customer Information  </div>\n  <div class=\"bullet-list-content\" > Customer Information will show details of Customer Developer Account. This shows Customer Id, Customer Account No, Email Id, iv-user, Name, Developer Created By and Developer Created On. Some of these information will be used in accessing APIs.</div>\n\n\n   <div class=\"bullet-list\" > OAuth2.0  </div>\n  <div class=\"bullet-list-content\" > Customer has to use unique Client Id and Client Secret mentioned in OAuth Credential table for Authentication of APIs.</div>\n  \n\n ## Usage Information\n This section provide Customer API usages details. This can show details based on different timestamps:       \n   \n ## Activating your first SIM \n\n <div id=\"auth-2.0-page\" ><section class=\"kong-doc\"><h2>Generating OAuth 2.0 token</h2> <p>\n       The OAuth 2.0 authorization code grant will be used by customer to gain access to protected\n       resources, such as APIs.\n       This set of APIs shall allow user to generate Access Token and refresh Access Token to perform\n       any action on CMP via the API gateway.\n     </p> <h2><a id=\"Request_an_Access_Token_0\"></a>Request an Access Token</h2> <p>To get a token by using the client Id &amp; Client Secret, send a POST request to the <code>/developer/generate/authtoken</code></p> <h1><a id=\"auth-request\"></a>Sample Request</h1> <pre><code>curl -X POST \"https://openapi.airtel.in/iot/api/developer/generate/authtoken\"\n         -H \"accept: application/json\"\n         -H \"apikey: XXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"iv-user: XXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"Content-Type: application/x-www-form-urlencoded\"\n         -d \"client_id=XXXXXXXXXXXXXXXXXXXXXX&amp;client_secret=XXXXXXXXXXXXXXXXXXXXXX\"\n       </code></pre> <h1><a id=\"auth-response\"></a>Sample Response</h1> <pre><code>{\n           \"data\": {\n             \"refresh_token\": \"XXXXXXXXXXXXXXXXXXXXXX\",\n             \"token_type\": \"bearer\",\n             \"access_token\": \"XXXXXXXXXXXXXXXXXXXXXX\",\n             \"expires_in\": 1800\n           }\n         }\n         </code></pre> &nbsp; &nbsp; &nbsp; &nbsp;You can generate same request response from Airtel IoT Developer Portal. To do so :\n           <ul><li>Navigate to <em>Documentation</em> → <em>Account Authorization</em> → <em>Generate Access Token</em> → <em>Test Endpoint</em></li> <li>Put values of <strong>apikey</strong>, <strong>client_id</strong>, <strong>client_secret</strong>, <strong>iv-user</strong> in mentioned text fields from Dashboard</li> <li><strong>Make API Call</strong>.</li></ul></section></div>\n\n <div id=\"sim-inventory-page\" ><section class=\"kong-doc\"><h1>Fetch SIM Inventory</h1> <p>\n       This API shall allow user to fetch the details of SIMs on that Customer\n       Account. It can fetch the details of one or more SIMs at a time.\n     </p> <h1><a id=\"sim-inventory-request\"></a>Sample Request</h1> \n     <pre><code>curl -X GET \"https://openapi.airtel.in/iot/api/customer/details/basket/0/sims\n       ?pageNo=1&amp;pageSize=1&amp;simStatus=INITIAL\"\n       -H \"accept: application/json\"\n       -H \"Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXX\"\n       -H \"apikey: XXXXXXXXXXXXXXXXXXXXXX\"\n       -H \"customer-id: XXXX\"\n       -H \"iv-user: XXXXXXXXXXXXXXXXXXXXXX\"\n     </code></pre> <h1><a id=\"sim-inventory-response\"></a>Sample Response</h1> <pre><code>{\n       \"data\":\n       {\n         \"sims\": [\n         {\n           \"simId\": \"5165173\",\n           \"mobileNo\": \"51967694502\",\n           \"simNo\": \"9999000000000000000\",\n           \"imsi\": \"30811010404043400\",\n           \"lsi\": \" \",\n           \"status\": \"INITIAL\",\n           \"isPaired\": \"0\",\n           \"isPrepaidSim\": \"0\",\n           \"circleName\": \"DELHI\",\n           \"planCode\": \"M2M_PLN_0324\",\n           \"planName\": \"VTS 49 special plan(without voice with sms)\",\n           \"description\": \"VTS 49 special plan(without voice with sms)\",\n           \"dataType\": \"2G\",\n           \"dataUnits\": \"250\",\n           \"planType\": \"0\"\n         }\n         ],\n         \"total\": \"10000\"\n       }\n     }\n     </code></pre> \n        &nbsp; &nbsp; &nbsp; &nbsp;You can generate same request response from Airtel IoT Developer Portal. To do so :\n       <ul><li>Navigate to <em>Documentation</em> → <em>Manage SIMs</em> → <em>Fetch SIMs</em> → <em>Test Endpoint</em></li> <li>Replace Bearer Token from access token generated from\n           <a id=\"go-to-auth\" class=\"nav-link\">Generating OAuth 2.0 token</a></li><li>Put values of <strong>apikey</strong>, <strong>iv-user</strong> &amp; <strong>customer-id</strong> in mentioned text fields from Dashboard.</li> <li>Select <strong>simStatus</strong> as <strong>INITIAL</strong></li> <li><strong>Make API Call</strong>.</li></ul></section></div>\n \n <div ><section class=\"kong-doc\"><h1 id=\"fetch-plans-page\">Fetch Plans</h1> <p>\n       This API shall allow user to fetch the details of Plans that are associated with the Customer\n       Account. It returns the Plan code, plan name, plan description and whether it is a test plan or\n       actual plan as defined on the account.\n     </p> <h1 id=\"fetchPlans-request\"> Sample Request</h1><h1><pre><code>curl -X GET \"https://openapi.airtel.in/iot/api/customer/details/plans\"\n         -H \"accept: application/json\"\n         -H \"Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"apikey: XXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"customer-id: XXXX\"\n         -H \"iv-user: XXXXXXXXXXXXXXXXXXXXXX\"\n       </code></pre></h1><h1 id=\"fetchPlans-response\">Sample Response</h1> <pre><code>{\n         \"data\": [\n         {\n           \"planCode\": \"M2M_PLN_0001\",\n           \"planName\": \"M2M-2G-1GB PLAN\",\n           \"planDescription\": \"M2M-2G-1GB PLAN\",\n           \"testPlan\": false\n         },\n         {\n           \"planCode\": \"M2M_PLN_0003\",\n           \"planName\": \"M2M 3G - 100 MB PLAN\",\n           \"planDescription\": \"M2M 3G - 100 MB PLAN\",\n           \"testPlan\": true\n         }\n         ]\n       }\n     </code></pre> &nbsp; &nbsp; &nbsp; &nbsp;You can generate same request response from Airtel IoT Developer Portal. To do so :\n         <ul><li>Navigate to <em>Documentation</em> → <em>Account Details</em> → <em>Fetch Customer Plans</em> → <em>Test Endpoint</em></li> <li>Replace Bearer Token from access token generated from\n             <a id=\"go-to-auth\" class=\"nav-link\">Generating OAuth 2.0 token</a></li> <li>Put values of <strong>apikey</strong>, <strong>iv-user</strong> &amp; <strong>customer-id</strong> in mentioned text fields from Dashboard.</li> <li><strong>Make API Call</strong>.</li></ul></section></div>\n       <div id=\"activate-sim-page\" ><section class=\"kong-doc\"><h1>Perform Activation</h1> <p>\n       This API shall allow user to change the state of SIM from Available (Initial to Activate) to\n       Active with Plan that is associated with the Billable account. It requires inputs as mobile\n       number and plan code.\n     </p> <h1 id=\"activate-sim-request\"> Sample Request</h1><h1><pre><code>curl -X POST \"https://openapi.airtel.in/iot/api/om/job/sim/activate\"\n         -H \"accept: application/json\"\n         -H \"Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"apikey: XXXXXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"customer-id: XXXX\"\n         -H \"iv-user: XXXXXXXXXXXXXXXXXXXXXXXXX\"\n         -H \"Content-Type: application/json\"\n         -d \"{ \\\"simDOList\\\": [ { \\\"mobileNO\\\": \\\"51967694502\\\",\n         \\\"planDO\\\": { \\\"planCode\\\": \\\"M2M_PLN_0001\\\" } } ]}\"\n       </code></pre></h1><h1><a id=\"activate-sim-response\"></a>Sample Response</h1> <pre><code>{\n       \"data\": {\n           \"jobId\": 795405,\n           \"jobType\": \"ACTIVATE_SIM\",\n           \"orderCount\": 0,\n           \"successCount\": 0,\n           \"failureCount\": 0,\n           \"inProgressCount\": 0,\n           \"rejectedCount\": 0,\n           \"orderInitiateDate\": \"25-04-2019 03:35:40 PM\",\n           \"statusMessage\": \"Your request is in progress\"\n       }\n   }\n   </code></pre> &nbsp; &nbsp; &nbsp; &nbsp;You can generate same request response from Airtel IoT Developer Portal. To do so :\n   <ul><li>Navigate to <em>Documentation</em> → <em>New Orders</em> → <em>Activate Sim</em> → <em>Activate Sim</em> → <em>Test Endpoint</em></li> <li>Replace Bearer Token from access token generated from\n     <a id=\"go-to-auth\" class=\"nav-link\">Generating OAuth 2.0 token</a></li> <li>Put values of <strong>apikey</strong>, <strong>iv-user</strong> &amp; <strong>customer-id</strong> in mentioned text fields from Dashboard.</li> <li>Put mobileNo in body fetched from response of API\n     <a id=\"go-to-sim-inventory\" class=\"nav-link\">Fetch SIM Inventory</a></li> <li>Put planCode in body fetched from response of API\n     <a id=\"go-to-fetch-plans\" class=\"nav-link\"> Fetch Plans </a></li> <li><strong>Make API Call</strong>.</li></ul><hr> <p><strong>NOTE</strong><br>\n   The JobId in the response is important to track the status of activation order. The details of JobId can be fetched from Fetch Jobs API. There shall be Order ID(s) within a JobId to view status of specific Order(s) in a JobId.</p> <hr></section></div>\n"
servers:
- url: https://m2m.airteliot.co.in/iot/api/
security: []
tags:
- name: Device & Session Information
  description: To data usage on a specific SIM, this API will allow user to get total data allocation, available data, used data, device information & session information for the SIM.
paths:
  /sim/device/info:
    get:
      tags:
      - Device & Session Information
      summary: Get Device Info
      description: Once the SIM is active on the network and inserted in a device to use data, this API will allow user to fetch device related parameters including IMEI, previous IMEI, device make / model, device type, etc.
      operationId: fetchDeviceInfoUsingGET
      parameters:
      - name: Authorization
        in: header
        description: Authorization Header (Value must be like Bearer <Developer Access Token>)
        required: true
        schema:
          type: string
          default: Bearer XXXXXXXXXXXXXX
      - name: apikey
        in: header
        description: Developer API Key
        required: true
        schema:
          type: string
      - name: customer-id
        in: header
        description: 'Unique ID to identify Customer (shared during On-Boarding process) '
        required: true
        schema:
          type: integer
          format: int64
      - name: iv-user
        in: header
        description: Developer Account User ID
        required: true
        schema:
          type: string
      - name: mobileNo
        in: query
        description: Mobile No.
        required: true
        allowEmptyValue: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceIMEIResponseVO'
        '400':
          description: Request Message is not correct
          content: {}
        '500':
          description: Internal Server Error.
          content: {}
      deprecated: false
  /sim/data/usage:
    get:
      tags:
      - Device & Session Information
      summary: Get Data Usage
      description: To fetch real-time data usage on a specific SIM, this API will allow user to get total data allocation, available data and used data for the SIM.
      operationId: fetchDataUsageUsingGET
      parameters:
      - name: Authorization
        in: header
        description: Authorization Header (Value must be like Bearer <Developer Access Token>)
        required: true
        schema:
          type: string
          default: Bearer XXXXXXXXXXXXXX
      - name: apikey
        in: header
        description: Developer API Key
        required: true
        schema:
          type: string
      - name: customer-id
        in: header
        description: 'Unique ID to identify Customer (shared during On-Boarding process) '
        required: true
        schema:
          type: integer
          format: int64
      - name: iv-user
        in: header
        description: Developer Account User ID
        required: true
        schema:
          type: string
      - name: mobileNo
        in: query
        description: Mobile No.
        required: true
        allowEmptyValue: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataUsageResponseVO'
        '400':
          description: Request Message is not correct
          content: {}
        '500':
          description: Internal Server Error.
          content: {}
      deprecated: false
  /device/diagnose/radius:
    get:
      tags:
      - Device & Session Information
      summary: Device Diagnose API.
      description: Fetch Device Diagnose Radius Attributes.
      operationId: deviceDiagnoseRadiusUsingGET
      parameters:
      - name: Authorization
        in: header
        description: Authorization Header (Value must be like Bearer <Developer Access Token>)
        required: true
        schema:
          type: string
          default: Bearer XXXXXXXXXXXXXX
      - name: apikey
        in: header
        description: Developer API Key
        required: true
        schema:
          type: string
      - name: customer-id
        in: header
        description: 'Unique ID to identify Customer (shared during On-Boarding process) '
        required: true
        schema:
          type: integer
          format: int64
      - name: endDate
        in: query
        description: End DateTime For AAA Radius.  Format DD/MM/YYYY
        allowEmptyValue: false
        schema:
          type: string
      - name: iv-user
        in: header
        description: Developer Account User ID
        required: true
        schema:
          type: string
      - name: mobileNo
        in: query
        description: Mobile No.
        required: true
        allowEmptyValue: false
        schema:
          type: string
      - name: pageNo
        in: query
        description: Page Number in case of pagination. Default Page No. is 1.
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        description: Page Size in pagination for AAA session details. Default Page Size is 20 and Maximum is 100.
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: startDate
        in: query
        description: Start DateTime For AAA Radius. Format DD/MM/YYYY
        allowEmptyValue: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceRadiusResponseVO'
        '400':
          description: Request Message is not correct
          content: {}
        '500':
          description: Internal Server Error.
          content: {}
      deprecated: false
  /bulk/dataUsages/download:
    post:
      tags:
      - Device & Session Information
      summary: Bulk Data Usage
      description: This API call is used to initiate download of Bulk data usage file from a specific Basket. It returns the file name along with creation and completion date for that basket. Since, the number of SIMs in a basket is restricted to 5000, hence the maximum number of SIMs in this Bulk data usage file will be 5000.
      operationId: downloadDataUsagesUsingPOST
      parameters:
      - name: Authorization
        in: header
        description: Authorization Header (Value must be like Bearer <Developer Access Token>)
        required: true
        schema:
          type: string
          default: Bearer XXXXXXXXXXXXXX
      - name: apikey
        in: header
        description: Developer API Key
        required: true
        schema:
          type: string
      - name: customer-id
        in: header
        description: 'Unique ID to identify Customer (shared during On-Boarding process) '
        required: true
        schema:
          type: integer
          format: int64
      - name: iv-user
        in: header
        description: Developer Account User ID
        required: true
        schema:
          type: string
      requestBody:
        description: basketDO
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasketDO'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadHistoryVO'
        '201':
          description: Resource Created Successfully
          content: {}
        '400':
          description: Request Message is not correct
          content: {}
        '500':
          description: Internal Server Error.
          content: {}
      deprecated: false
      x-codegen-request-body-name: basketDO
components:
  schemas:
    BasketDO:
      title: BasketDO
      required:
      - basketId
      type: object
      properties:
        basketId:
          type: integer
          description: Basket ID
          format: int64
    DownloadHistoryVO:
      title: DownloadHistoryVO
      type: object
      properties:
        basketName:
          type: string
          description: Basket Name
        completionDate:
          type: string
          description: Download Request Completion Date and Time
        creationDate:
          type: string
          description: Download Request Creation Date and Time
        downloadFileId:
          type: integer
          description: Download Request ID
          format: int64
        downloadType:
          type: string
          description: Download Type
        extension:
          type: string
          description: File Extension
        fileName:
          type: string
          description: File Name
        progress:
          type: integer
          description: File Download Progress
          format: int32
        status:
          type: string
          description: Download Status
    DeviceFrequencyDO:
      title: DeviceFrequencyDO
      type: object
      properties:
        band:
          type: string
        technology:
          type: string
    DeviceIMEIResponseVO:
      title: DeviceIMEIResponseVO
      type: object
      properties:
        deviceAttributes:
          type: array
          description: Device Attributes List
          items:
            $ref: '#/components/schemas/DeviceAttributesDO'
        deviceFrequencies:
          type: array
          description: Device Frequencies List.
          items:
            $ref: '#/components/schemas/DeviceFrequencyDO'
        deviceIMEI:
          type: string
          description: Device IMEI
        deviceIMEIChanged:
          type: boolean
        deviceModelNumber:
          type: string
          description: Device Model Number.
        deviceName:
          type: string
          description: Device Name
        deviceType:
          type: string
          description: Device Type
        operatingSystemName:
          type: string
          description: Operating System Name.
        operatingSystemProvider:
          type: string
          description: Operating System Provider
        operatingSystemVersion:
          type: string
          description: Operating System Version
        otaSupport:
          type: string
          description: OTA Support
        previousDeviceIMEI:
          type: string
          description: Previous Device IMEI
    DataUsageResponseVO:
      title: DataUsageResponseVO
      type: object
      properties:
        basketName:
          type: string
          description: Basket Name
        dataSegregation:
          $ref: '#/components/schemas/DataSegregation'
        dataUsageFound:
          type: boolean
        dataUsageUnits:
          type: string
        error:
          type: string
          description: Error Message
        mobileNo:
          type: string
          description: Mobile Number
        planCode:
          type: string
          description: Plan Code
        planName:
          type: string
          description: Plan Name
        prepaid:
          type: boolean
        remainingDataUsage:
          type: string
          description: Remaining Data
        simNo:
          type: string
          description: SIM Number
        totalDataUsage:
          type: string
          description: Total Data Usage
        usedDataUsage:
          type: string
          description: Used Data
    DataSegregation:
      title: DataSegregation
      type: object
      properties:
        activePlanQuota:
          $ref: '#/components/schemas/ActivePlanQuota'
        rolloverQuota:
          $ref: '#/components/schemas/RolloverQuota'
    ActivePlanQuota:
      title: ActivePlanQuota
      type: object
      properties:
        allocatedQuota:
          type: string
        availableQuota:
          type: string
        quotaUnit:
          type: string
    DeviceAttributesDO:
      title: DeviceAttributesDO
      type: object
      properties:
        attrName:
          type: string
        attrValue:
          type: string
    RadiusObjects:
      title: RadiusObjects
      type: object
      properties:
        3GPPIMEISV:
          type: string
        3GPPIMSI:
          type: string
        3GPPIMSIMCCMNC:
          type: string
        3GPPRATType:
          type: string
        3GPPSessionStopIndicator:
          type: integer
          format: int64
        acctInputPackets:
          type: string
        acctOutputPackets:
          type: string
        acctSessionId:
          type: string
        acctStatusType:
          type: string
        acctTerminateCause:
          type: string
        calledStationId:
          type: string
        callingStationId:
          type: string
        framedIPAddress:
          type: string
        sessionStartTimestamp:
          type: string
        sessionStopTimestamp:
          type: string
        totalActiveSession:
          type: string
    RolloverQuota:
      title: RolloverQuota
      type: object
      properties:
        allocatedQuota:
          type: string
        availableQuota:
          type: string
        quotaUnit:
          type: string
    DeviceRadiusResponseVO:
      title: DeviceRadiusResponseVO
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RadiusObjects'
        resCode:
          type: string
        resStatus:
          type: string
        totalCount:
          type: integer
          format: int32
x-tagGroups:
- name: Manage Customer APIs
  tags:
  - Account Authorization
  - Account Details
  - Inventory Management
- name: New Orders APIs
  tags:
  - SIM LifeCycle
- name: Bulk Orders APIs
  tags:
  - SIM LifeCycle Bulk
- name: Jobs APIs
  tags:
  - Job Status
- name: Device Details APIs
  tags:
  - Device & Session Information
- name: Whitelisting APIs
  tags:
  - Whitelisting
- name: KYC APIs
  tags:
  - KYC Manager
- name: Messaging Centre APIs
  tags:
  - Messaging Centre