API docs by Redocly

Locate API Catalog (1.4.8)

Download OpenAPI specification:Download

Support: locate.support@airtel.com

Airtel Locate platform enables enterprises and small businesses to easily track device location to enhance their IoT use cases irrespective of device's GPS capabilities. Airtel Locate APIs will allow you to easily get Assets' location and manage consent.

Key word :

  • MSISDN – represents a valid 10 or 13 digit airtel mobile number
  • Locate – Airtel Locate platform
  • Resource – a resource is equivalent to a MSISDN
  • Location – location of the resource
  • License – represents an Airtel Locate customer’s commercial license to use location API’s

Authorization API

This API will help you to generate token from the client credentials shared upon subscription to location services. In case you have not yet subscribed to location service, email us to locate.support@airtel.com

Generate Oauth token

This API will generate Access Token for given scope. Generated token will be valid for 24 hours. To access Airtel Locate APIs, user will need generated access token.

path Parameters
customerBaId
required
string

customerBaId

Request Body schema: application/json
required

credentials

client_id
required
string
client_secret
required
string
scope
required
string
Enum: "location" "resource"

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "scope": "location"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "token_type": "string"
}

Location API

This API will return location of MSISDN including Latitude and Longitude.

Get Location

This API shall allow user to fetch the location of the registered resource. The access token must be generated with “location” scope for using this API. The value for query parameter “type” is ”sync” for synchronous request and ”async” for asynchronous request and the default value is ”sync”. Customer need to register the callback listener for the async API where Locate would post the location.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

query Parameters
type
required
string
Default: "sync"
Example: type=async

type

header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "location": {
    },
  • "message": "string",
  • "retrievedAt": "yyyy-MM-dd HH:mm:ss",
  • "status": "string"
}

Validation API

These set of APIs allow customer to validate a physical address against network fetched live location. To get access to these API's please email to locate.support@airtel.com

Address validation API

API to get the distance between live network location and given physical address.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

header Parameters
access_token
required
string
Request Body schema: application/json
required

address

address
required
string

address to be validated

Responses

Request samples

Content type
application/json
{
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "distance": 0.1,
  • "distanceUnit": "string",
  • "geocode": {
    },
  • "message": "string",
  • "networkCoordinates": {
    },
  • "status": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Tenant API

These set of Tenant APIs allow customer to initiate consent, fetch consent details, delete consent, fetch list of msisdn for consent was initiated and various other API to handle tenant msisdn's and their consent.

Fetch Customer Tenants

This API returns the list of tenants registered by customer.

path Parameters
customerBaId
required
string

customerBaId

query Parameters
offset
integer <int64>
organizationName
string

organizationName

pageNumber
integer <int32>
pageSize
integer <int32>
paged
boolean
profileNeeded
string

profileNeeded

sort.sorted
boolean
sort.unsorted
boolean
unpaged
boolean
header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "consentChannels": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "customerBaId": "string",
  • "id": 0,
  • "organizationName": "string",
  • "profile": {
    }
}

Fetch Tenant Consent purpose

This API returns the list of available tenant consent purpose for initiating consent. This API returns the list of consent purpose for which consent can be initiated by customer for location tracking.

path Parameters
customerBaId
required
string

customerBaId

query Parameters
offset
integer <int64>
pageNumber
integer <int32>
pageSize
integer <int32>
paged
boolean
sort.sorted
boolean
sort.unsorted
boolean
unpaged
boolean
header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "purposeKey": "string",
  • "purposeValue": "string"
}

Fetch MSISDNs

This API returns the list of resource registered by customer for location tracking. Optional query params consent, tracking and daysSinceLastLocationFetched can be used to further filter the result.This API returns the list of resource for which consent initiated by customer for location tracking.

path Parameters
customerBaId
required
string

customerBaId

tenantId
required
string

tenantId

query Parameters
consent
string
Example: consent=PENDING

consent

daysSinceLastLocationFetched
string
Example: daysSinceLastLocationFetched=10

daysSinceLastLocationFetched

offset
integer <int64>
pageNumber
integer <int32>
pageSize
integer <int32>
paged
boolean
sort.sorted
boolean
sort.unsorted
boolean
tracking
string
Example: tracking=true

tracking

unpaged
boolean
header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "consent": "PROCESSING",
  • "consentPurpose": "string",
  • "language": "EN",
  • "lastFetchedLocationTimestamp": "2019-08-24T14:15:22Z",
  • "msisdn": "string",
  • "name": "string",
  • "tracking": true
}

Initiate Consent

This API shall allow the customer to initiate consent on number prefixed by 91 via available channel. Current supported channels are IVR and SMS. Use this to

  • Initiating new consent
  • Initiating consent if current state is REJECTED
  • Initiate consent in different language then previous

Supported Language English(en) | Hindi(hi) | Assamese(as) | Bengali(bn) | Oriya(or) | Kannada(kn) | Malayalam(ml) | Tamil(ta) | Telugu(te)

Sample Message:

  • Customer with short code :To allow ABC Pvt Ltd. to fetch your location using your SIM Provider, please reply "Y" (Toll Free).
  • Customer without short code: To allow ABC Pvt Ltd. to fetch your location using your SIM Provider, please reply "{unique_id} Y" (Toll Free).
path Parameters
customerBaId
required
string

customerBaId

tenantId
required
string

tenantId

header Parameters
access_token
required
string
Request Body schema: application/json
required

consentRequest

channel
string

The channel to initiate consent. Defaults to SMS

language
string

Preferred language to initiate the consent. Default to EN(english)

msisdn
required
string

The Airtel number must be prefixed with 91 followed by 10 digit mobile number.

purpose
required
string

The purpose to initiate consent.

Responses

Request samples

Content type
application/json
{
  • "channel": "SMS",
  • "language": "EN",
  • "msisdn": "91XXXXXXXXXX",
  • "purpose": "TRACKING"
}

Search Resource

This API will return the details for requested MSISDN like name, consent status and tracking status.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

tenantId
required
string

tenantId

header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "consent": "PROCESSING",
  • "consentPurpose": "string",
  • "language": "EN",
  • "lastFetchedLocationTimestamp": "2019-08-24T14:15:22Z",
  • "msisdn": "string",
  • "name": "string",
  • "tracking": true
}

Remove MSISDN

This API will allow you to remove a MSISDN. It requires customer ID and MSISDN to be deleted.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

tenantId
required
string

tenantId

header Parameters
access_token
required
string

Responses

Modify Resource

API to modify tracking and alias(name) for registered msisdn.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

tenantId
required
string

tenantId

header Parameters
access_token
required
string
Request Body schema: application/json
required

resourcePatchOptions

alias
string

The name to msisdn for which consent was initiated

isTrackingEnabled
boolean

enable/disable tracking for a MSISDN.

Responses

Request samples

Content type
application/json
{
  • "alias": "Albert Einstein",
  • "isTrackingEnabled": true
}

Fetch Consent Details

API to get the consent details insight

Consent States -- PROCESSING | INITIATED | PENDING | ALLOWED | REJECTED | FAILED

Consent Events Types -- MT | DR | MO | CALL | CDR

  • MT- Event when platform sends consent via SMS
  • DR- Event when delivery report is received against a sent MT event
  • MO- Event when platform receives a valid consent sent by user via SMS
  • CALL- Event when platform initiates consent call via IVR
  • CDR- Event when platform receives call data record against the initiated CALL event
path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

tenantId
required
string

tenantId

header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "channel": "IVR",
  • "consent": "PROCESSING",
  • "events": [
    ],
  • "lastRecordedConsent": "PROCESSING",
  • "lastRecordedConsentChannel": "IVR",
  • "lastRecordedConsentUpdatedAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get Location

This API shall allow user to fetch the location of the registered resource. The access token must be generated with “location” scope for using this API. The value for query parameter “type” is ”sync” for synchronous request and ”async” for asynchronous request and the default value is ”sync”. Customer need to register the callback listener for the async API where Locate would post the location.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

tenantId
required
string

tenantId

query Parameters
type
required
string
Default: "sync"
Example: type=async

type

header Parameters
access_token
required
string

Responses

Response samples

Content type
application/json
{
  • "location": {
    },
  • "message": "string",
  • "retrievedAt": "yyyy-MM-dd HH:mm:ss",
  • "status": "string"
}

Address validation API

API to get the distance between live network location and given physical address.

path Parameters
customerBaId
required
string

customerBaId

msisdn
required
string

msisdn

tenantId
required
string

tenantId

header Parameters
access_token
required
string
Request Body schema: application/json
required

address

address
required
string

address to be validated

Responses

Request samples

Content type
application/json
{
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "distance": 0.1,
  • "distanceUnit": "string",
  • "geocode": {
    },
  • "message": "string",
  • "networkCoordinates": {
    },
  • "status": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}