openapi: 3.2.0 info: version: '1.0' title: Airtel IoT SIM LifeCycle API contact: email: m2m.support@airtel.com description: "# Overview\n ## Introduction\n
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.
\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
Key Authentication
\n
A Unique Identification Secret Key per Customer, must be passed in Headers while calling API and will be used for Authentication purpose.
\n \n\n
Customer Information
\n
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.
\n\n\n
OAuth2.0
\n
Customer has to use unique Client Id and Client Secret mentioned in OAuth Credential table for Authentication of APIs.
\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

Generating OAuth 2.0 token

\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

Request an Access Token

To get a token by using the client Id & Client Secret, send a POST request to the /developer/generate/authtoken

Sample Request

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&client_secret=XXXXXXXXXXXXXXXXXXXXXX\"\n       

Sample Response

{\n           \"data\": {\n             \"refresh_token\": \"XXXXXXXXXXXXXXXXXXXXXX\",\n             \"token_type\": \"bearer\",\n             \"access_token\": \"XXXXXXXXXXXXXXXXXXXXXX\",\n             \"expires_in\": 1800\n           }\n         }\n         
       You can generate same request response from Airtel IoT Developer Portal. To do so :\n
\n\n

Fetch SIM Inventory

\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

Sample Request

\n
curl -X GET \"https://openapi.airtel.in/iot/api/customer/details/basket/0/sims\n       ?pageNo=1&pageSize=1&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     

Sample Response

{\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     
\n        You can generate same request response from Airtel IoT Developer Portal. To do so :\n
\n \n

Fetch Plans

\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

Sample Request

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       

Sample Response

{\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     
       You can generate same request response from Airtel IoT Developer Portal. To do so :\n
\n

Perform Activation

\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

Sample Request

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       

Sample Response

{\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   
       You can generate same request response from Airtel IoT Developer Portal. To do so :\n

NOTE
\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.


\n" servers: - url: https://m2m.airteliot.co.in/iot/api/ security: [] tags: - name: SIM LifeCycle description: This API shall allow user to change the state of SIMs. paths: /job/activate/sim/from/test: post: tags: - SIM LifeCycle summary: Activate SIM from Test Mode description: This API shall allow user to change the Bill Plan on a particular SIM from test plan to the commercial plan associated with that Billable account. It requires inputs as mobile number and target plan code. operationId: activateSimFromTestUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: changePlanOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrderWithPlan' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: changePlanOrder /job/change/plan: post: tags: - SIM LifeCycle summary: Change Plan description: This API shall allow user to change the Bill Plan on a particular SIM from one Plan to the other Plan associated with that Billable account. It requires inputs as mobile number and target plan code. operationId: changePlanUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: changePlanOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrderWithPlan' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: changePlanOrder /job/sim/activate: post: tags: - SIM LifeCycle summary: Activate SIM description: This API shall allow user to change the state of SIM from Available (Ready to Activate) to Active with Plan that is associated with the Billable account. It requires inputs as mobile number and plan code. operationId: activateSimsUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: generateOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrderWithPlan' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: generateOrder /job/sim/swap: post: tags: - SIM LifeCycle summary: Swap SIM description: In case the user wishes to replace SIM card associated with a Mobile number, in case of any issue with the SIM, this API shall allow user to change the SIM on that Billable account. It requires inputs as source SIM and target SIM number. operationId: swapSimUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: swapSim content: application/json: schema: $ref: '#/components/schemas/SwapSim' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: swapSim /job/sim/voluntary/suspend: post: tags: - SIM LifeCycle summary: Safe Custody description: In case the user wishes to voluntarily suspend the SIM card for sometime, there is an option to put the SIM in safe custody. This API shall allow user to put the SIM in safe custody on that Billable account. It requires inputs as mobile number. operationId: safeCustodyUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: generateOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrder' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: generateOrder /job/sim/voluntary/resume: post: tags: - SIM LifeCycle summary: Out of Safe Custody description: In case the user wishes to change the number state from Suspended to Active state, this API shall allow user to do the same on that Billable account. It requires inputs as mobile number. operationId: outOfSafeCustodyUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: generateOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrder' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: generateOrder /job/temp/disconnect: post: tags: - SIM LifeCycle summary: Temp Disconnection description: This API is used to initiate disconnection of M2M SIMs. Initially, SIMs will go into temporary disconnection for 5 days and then SIMs will be permanently disconnected on completion of 5 days. operationId: tempDisconnectionUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: generateOrder content: application/json: schema: $ref: '#/components/schemas/GeneratedTempDisconnectOrder' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: generateOrder /job/td/resume: post: tags: - SIM LifeCycle summary: Resume from TD description: This API is used to resume SIMs from temporary disconnection within 5 days of initiation of disconnection. operationId: tdResumeUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: generateOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrder' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: generateOrder /job/activate/test/sims: post: tags: - SIM LifeCycle summary: Activate SIM in Test Mode description: This API shall allow user to change the state of SIM from Available (Ready to Activate) to Activate in Test Mode. It requires inputs as mobile number and plan code. operationId: activateTestSimsUsingPOST parameters: - name: Authorization in: header description: Authorization Header (Value must be like Bearer ) 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: generateOrder content: application/json: schema: $ref: '#/components/schemas/GenerateOrderWithPlan' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobVO' '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: generateOrder components: schemas: GenerateOrderWithPlan: title: GenerateOrderWithPlan required: - simDOList type: object properties: simDOList: type: array description: List of SIM items: $ref: '#/components/schemas/SimDOWithPlan' SwapSim: title: SwapSim type: object properties: existingSIMNo: type: string newSIMNo: type: string SimDO: title: SimDO required: - mobileNO type: object properties: mobileNO: type: string description: Mobile No. GeneratedTempDisconnectOrder: title: GeneratedTempDisconnectOrder required: - reason - simDOList type: object properties: reason: type: string description: Disconnection Reason. enum: - NUMBER_NOT_REQUIRED - PRICING_CONCERN - NETWORK_COVERAGE_ISSUE - BILLING_OR_COLLECTION_ISSUE - CONTRACT_EXPIRED simDOList: type: array description: List of SIM items: $ref: '#/components/schemas/SimDO' GenerateOrder: title: GenerateOrder required: - simDOList type: object properties: simDOList: type: array description: List of SIM items: $ref: '#/components/schemas/SimDO' SimDOWithPlan: title: SimDOWithPlan required: - mobileNO type: object properties: mobileNO: type: string description: Mobile No. planDO: $ref: '#/components/schemas/PlanDO' PlanDO: title: PlanDO required: - planCode type: object properties: planCode: type: string description: Plan Code JobVO: title: JobVO type: object properties: errorFileName: type: string description: Error File Name errorItemsCount: type: integer description: Count of Error items in uploaded file. format: int32 failureCount: type: integer description: Failure Order Count format: int32 inProgressCount: type: integer description: In Progress Order Count format: int32 jobId: type: integer description: Job ID, in case a particular Job ID to be fetched format: int64 jobType: type: string description: Job Type as defined in CMP orderCompletionTime: type: string description: End Date in a date range to fetch Job IDs orderCount: type: integer description: Order Count format: int32 orderInitiateDate: type: string description: Start Date in a date range to fetch Job IDs rejectedCount: type: integer description: Rejected Order Count format: int32 requestedOrderItems: type: integer description: Count of items requested in uploaded file. format: int32 statusCode: type: string description: Job Status Code statusMessage: type: string description: Status of Job IDs successCount: type: integer description: Success Order Count format: int32 uploadFileName: type: string description: Upload File Name 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