openapi: 3.0.1
info:
version: ''
title: Airtel IoT
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 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 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 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 - Navigate\
\ to Documentation → Account Authorization → Generate Access Token → Test\
\ Endpoint
- Put values of apikey, client_id, client_secret,\
\ iv-user in mentioned text fields from Dashboard
- Make API Call.
\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\
\ - Navigate to Documentation → Manage SIMs → Fetch SIMs →\
\ Test Endpoint
- Replace Bearer Token from access token generated from\n \
\ Generating OAuth 2.0 token
- Put values of apikey,\
\ iv-user & customer-id in mentioned text fields from Dashboard.
\
\ - Select simStatus as INITIAL
- Make API Call.
\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 - Navigate to\
\ Documentation → Account Details → Fetch Customer Plans → Test Endpoint
\
\ - Replace Bearer Token from access token generated from\n Generating OAuth 2.0 token
- Put values of apikey, iv-user\
\ & customer-id in mentioned text fields from Dashboard.
- Make\
\ API Call.
\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 - Navigate\
\ to Documentation → New Orders → Activate Sim → Activate Sim\
\ → Test Endpoint
- Replace Bearer Token from access token generated from\n Generating OAuth 2.0 token
- Put values of apikey,\
\ iv-user & customer-id in mentioned text fields from Dashboard.
\
\ - Put mobileNo in body fetched from response of API\n Fetch SIM Inventory
- Put planCode in body fetched from response of API\n \
\ Fetch Plans
- Make API Call.
\
\ 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"
security: []
servers:
- url: https://m2m.airteliot.co.in/iot/api/
tags:
- name: Account Authorization
description: This set of APIs shall allow user to generate Access Token and refresh Access Token to
perform any action on CMP via the API gateway.
- name: SIM LifeCycle
description: This API shall allow user to change the state of SIMs.
- name: SIM LifeCycle Bulk
description: This API shall allow user to change the state of SIMs.
- name: Job Status
description: This API will allow user to fetch Job details for any operations being performed in that
Billable account.
- 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.
- name: Whitelisting
description: This set of APIs to manage whitelisting numbers on Airtel IoT portal in Batch
- name: KYC Manager
description: This set of APIs to manage SIM KYC details.
- name: Messaging Centre
description: These set of APIs allow lifecycle management of the Messaging Centre functionality
- name: Account Details
description: This set of APIs fetch various details about a Billable Customer Account including Customer
Profile, Plan details, User details and so on.
- name: Inventory Management
description: This set of APIs fetch various details about Sim details, Basket details and so on in the
account.
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
paths:
/auth/v2/generate/authtoken:
post:
tags:
- Account Authorization
summary: Generate Access Token
description: This API shall allow user to generate Access Token to be used while doing any operations
on the portal via APIs. **As per our recent upgrade, a new attribute 'refresh_expires_in' has
been added to the response field which would display the time (in seconds) after which the refresh
token would expire.**
operationId: generateAccessTokenUsingPOST
parameters:
- name: apikey
in: header
description: apikey
required: true
schema:
type: string
- name: iv-user
in: header
description: Developer Account User ID
required: true
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
required:
- client_id
- client_secret
properties:
client_id:
type: string
description: Unique ID to Authorize Customer (shared during On-Boarding process)
client_secret:
type: string
description: Developer Account Secret Key (shared during On-Boarding process) that shall
be used to generate Token
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties:
type: object
properties: {}
'201':
description: Resource Created Successfully
content: {}
'400':
description: Request Message is not correct
content: {}
'500':
description: Internal Server Error.
content: {}
deprecated: false
/auth/v2/refresh/authtoken:
post:
tags:
- Account Authorization
summary: Refresh Access Token
description: This API shall allow user to refresh Access Token to be used while doing any operations
on the portal via APIs.
operationId: refreshAccessTokenUsingPOST
parameters:
- name: apikey
in: header
description: apikey
required: true
schema:
type: string
- name: iv-user
in: header
description: Developer Account User ID
required: true
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
required:
- refresh_token
properties:
refresh_token:
type: string
description: Token used to refresh access_token
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties:
type: object
properties: {}
'201':
description: Resource Created Successfully
content: {}
'400':
description: Request Message is not correct
content: {}
'500':
description: Internal Server Error.
content: {}
deprecated: false
/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