Bharti Airtel Tenant API

openapi: 3.2.0
info:
  description: 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.
  version: 1.4.8
  title: Locate API Catalog Tenant API
  contact:
    name: Support
    email: locate.support@airtel.com
servers:
- url: https://openapi.airtel.in/
tags:
- name: Tenant API
  description: 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.
paths:
  /locate/apis/customers/{customerBaId}/tenants:
    get:
      tags:
      - Tenant API
      summary: Fetch Customer Tenants
      description: This API returns the list of tenants registered by customer.
      operationId: getCustomerTenantsUsingGET_1
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: organizationName
        in: query
        description: organizationName
        required: false
        schema:
          type: string
      - name: pageNumber
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: paged
        in: query
        required: false
        schema:
          type: boolean
      - name: profileNeeded
        in: query
        description: profileNeeded
        required: false
        schema:
          type: string
      - name: sort.sorted
        in: query
        required: false
        schema:
          type: boolean
      - name: sort.unsorted
        in: query
        required: false
        schema:
          type: boolean
      - name: unpaged
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerTenantResponseDto'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/consent/purpose:
    get:
      tags:
      - Tenant API
      summary: Fetch Tenant Consent purpose
      description: 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.
      operationId: getAllConsentPurposeUsingGET_1
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: pageNumber
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: paged
        in: query
        required: false
        schema:
          type: boolean
      - name: sort.sorted
        in: query
        required: false
        schema:
          type: boolean
      - name: sort.unsorted
        in: query
        required: false
        schema:
          type: boolean
      - name: unpaged
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentPurpose'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/{tenantId}/resources:
    get:
      tags:
      - Tenant API
      summary: Fetch MSISDNs
      description: 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.
      operationId: findAllUsingGET_3
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: consent
        in: query
        description: consent
        required: false
        allowEmptyValue: false
        example: PENDING
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: daysSinceLastLocationFetched
        in: query
        description: daysSinceLastLocationFetched
        required: false
        allowEmptyValue: false
        example: '10'
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: pageNumber
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: paged
        in: query
        required: false
        schema:
          type: boolean
      - name: sort.sorted
        in: query
        required: false
        schema:
          type: boolean
      - name: sort.unsorted
        in: query
        required: false
        schema:
          type: boolean
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      - name: tracking
        in: query
        description: tracking
        required: false
        allowEmptyValue: false
        example: 'true'
        schema:
          type: string
      - name: unpaged
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponseDto'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/{tenantId}/resources/consent:
    post:
      tags:
      - Tenant API
      summary: Initiate Consent
      description: '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).'
      operationId: initiateConsentUsingPOST_4
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantConsentRequest'
        description: consentRequest
        required: true
      responses:
        '202':
          description: accepted
        '400':
          description: "Bad Request\n   • Invalid language\n   • Not an airtel number\n   • Invalid channel"
        '401':
          description: Unauthorized
        '403':
          description: Forbidden consent state or channel
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/{tenantId}/resources/{msisdn}:
    get:
      tags:
      - Tenant API
      summary: Search Resource
      description: This API will return the details for requested MSISDN like name, consent status and tracking status.
      operationId: searchUsingGET_3
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: msisdn
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponseDto'
      deprecated: false
    delete:
      tags:
      - Tenant API
      summary: Remove MSISDN
      description: This API will allow you to remove a MSISDN. It requires customer ID and MSISDN to be deleted.
      operationId: deleteResourceUsingDELETE_4
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: msisdn
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted Successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Msisdn not found for customer
      deprecated: false
    patch:
      tags:
      - Tenant API
      summary: Modify Resource
      description: API to modify tracking and alias(name) for registered msisdn.
      operationId: patchResourceUsingPATCH_4
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: msisdn
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/ResourcePatchOptions'
      responses:
        '204':
          description: Successfully updated
        '400':
          description: Bad Request in case of bad json body
        '401':
          description: Unauthorized
        '403':
          description: Forbidden if number issued licenses exhausted
        '404':
          description: Msisdn not found for customer
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/{tenantId}/resources/{msisdn}/consent:
    get:
      tags:
      - Tenant API
      summary: Fetch Consent Details
      description: '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_'
      operationId: getConsentUsingGET_3
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: msisdn
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Msisdn not found for customer
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/{tenantId}/resources/{msisdn}/location:
    get:
      tags:
      - Tenant API
      summary: Get Location
      description: 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.
      operationId: getLocationForTenantsUsingGET_1
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: msisdn
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: type
        required: true
        allowEmptyValue: false
        example: async
        schema:
          type: string
          default: sync
      responses:
        '200':
          description: Ok - successful synchronous location request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponse'
        '202':
          description: Accepted - successful asynchronous location request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncCorrelationId'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: "Forbidden-  \n Subscription expired | Subscription limit reached || resource has not given consent | tracking is disabled | callback url is not registered"
        '404':
          description: Not Found
        '429':
          description: Request for location fetch can before location rate issues in license| Location request in progress for given msisdn
        '502':
          description: "Error in Fetching location of msisdn because of network error in HLR, \n MME, MSC. The ~5-10% of such error is expected."
      deprecated: false
  /locate/apis/customers/{customerBaId}/tenants/{tenantId}/resources/{msisdn}/validation/address:
    post:
      tags:
      - Tenant API
      summary: Address validation API
      description: API to get the distance between live network location and given physical address.
      operationId: addressValidationForTenantsUsingPOST_1
      parameters:
      - name: access_token
        in: header
        required: true
        schema:
          type: string
      - name: customerBaId
        in: path
        description: customerBaId
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: msisdn
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        description: tenantId
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/AddressValidationDto'
      responses:
        '200':
          description: Ok - successful address validation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponseDto'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: "Forbidden-  \nresource has not given consent | tracking is disabled "
        '404':
          description: Not Found
        '502':
          description: "Error in Fetching location of msisdn because of network error in HLR, \n MME, MSC. The ~5-10% of such error is expected.| Error retrieving geocode while processing request. Please try again!"
      deprecated: false
components:
  schemas:
    CustomerTenantResponseDto:
      type: object
      properties:
        active:
          type: boolean
        consentChannels:
          type: array
          items:
            type: string
            enum:
            - IVR
            - SMS
        createdAt:
          type: string
          format: date-time
        customerBaId:
          type: string
        id:
          type: integer
          format: int64
        organizationName:
          type: string
        profile:
          $ref: '#/components/schemas/CustomerTenantProfileResponseDto'
      title: CustomerTenantResponseDto
    ConsentEvents:
      type: object
      properties:
        channel:
          type: string
          enum:
          - IVR
          - SMS
        consentId:
          type: string
        initiatedBy:
          type: string
          enum:
          - PLATFORM
          - CUSTOMER
        meta:
          $ref: '#/components/schemas/ConsentEventMeta'
        status:
          type: string
          enum:
          - FAIL
          - SUCCESS
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          enum:
          - MT
          - DR
          - MO
          - CALL
          - CDR
      title: ConsentEvents
    TenantConsentRequest:
      type: object
      required:
      - msisdn
      - purpose
      properties:
        channel:
          type: string
          example: SMS
          description: The channel to initiate consent. Defaults to SMS
        language:
          type: string
          example: EN
          description: Preferred language to initiate the consent. Default to EN(english)
        msisdn:
          type: string
          example: 91XXXXXXXXXX
          description: The Airtel number must be prefixed with 91 followed by 10 digit mobile number.
        purpose:
          type: string
          example: TRACKING
          description: The purpose to initiate consent.
      title: TenantConsentRequest
    ResourceResponseDto:
      type: object
      properties:
        consent:
          type: string
          enum:
          - PROCESSING
          - INITIATED
          - ALLOWED
          - PENDING
          - REJECTED
          - FAILED
        consentPurpose:
          type: string
        language:
          type: string
          enum:
          - EN
          - HI
          - AS
          - BN
          - OR
          - KN
          - ML
          - TA
          - TE
        lastFetchedLocationTimestamp:
          type: string
          format: date-time
        msisdn:
          type: string
        name:
          type: string
        tracking:
          type: boolean
      title: ResourceResponseDto
    LatLong:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        radius:
          type: string
      title: LatLong
    LocationResponse:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/LatLong'
        message:
          type: string
        retrievedAt:
          type: string
          format: date-time
          example: yyyy-MM-dd HH:mm:ss
          description: location
        status:
          type: string
      title: LocationResponse
    ConsentResponse:
      type: object
      properties:
        channel:
          type: string
          enum:
          - IVR
          - SMS
        consent:
          type: string
          enum:
          - PROCESSING
          - INITIATED
          - ALLOWED
          - PENDING
          - REJECTED
          - FAILED
        events:
          type: array
          items:
            $ref: '#/components/schemas/ConsentEvents'
        lastRecordedConsent:
          type: string
          enum:
          - PROCESSING
          - INITIATED
          - ALLOWED
          - PENDING
          - REJECTED
          - FAILED
        lastRecordedConsentChannel:
          type: string
          enum:
          - IVR
          - SMS
        lastRecordedConsentUpdatedAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      title: ConsentResponse
    GeocodeDetails:
      type: object
      properties:
        formattedAddress:
          type: string
          description: this shows the formatted address of the POI.
        geocodeLevel:
          type: string
          description: this shows on which level the POI has been geocoded.
        inputAddress:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
      title: GeocodeDetails
    AddressValidationDto:
      type: object
      required:
      - address
      properties:
        address:
          type: string
          example: string
          description: address to be validated
      title: AddressValidationDto
    ConsentPurpose:
      type: object
      properties:
        purposeKey:
          type: string
        purposeValue:
          type: string
      title: ConsentPurpose
    CustomerTenantProfileResponseDto:
      type: object
      properties:
        address:
          type: string
        city:
          type: string
        customerSpocContactNumber:
          type: string
        customerSpocEmail:
          type: string
        customerSpocName:
          type: string
        pincode:
          type: string
        state:
          type: string
      title: CustomerTenantProfileResponseDto
    ConsentEventMeta:
      type: object
      properties:
        callStatus:
          type: string
        consentId:
          type: string
        delivered:
          type: boolean
        keyPressed:
          type: boolean
        language:
          type: string
          enum:
          - EN
          - HI
          - AS
          - BN
          - OR
          - KN
          - ML
          - TA
          - TE
      title: ConsentEventMeta
    ResourcePatchOptions:
      type: object
      properties:
        alias:
          type: string
          example: Albert Einstein
          description: The name to msisdn for which consent was initiated
        isTrackingEnabled:
          type: boolean
          example: true
          description: enable/disable tracking for a MSISDN.
      title: ResourcePatchOptions
    AddressValidationResponseDto:
      type: object
      properties:
        distance:
          type: number
          format: double
        distanceUnit:
          type: string
          description: Km/m
        geocode:
          $ref: '#/components/schemas/GeocodeDetails'
        message:
          type: string
          description: when the subscriber is absent or in restricted zone.
        networkCoordinates:
          $ref: '#/components/schemas/LatLong'
        status:
          type: string
        timestamp:
          type: string
          format: date-time
      title: AddressValidationResponseDto
    AsyncCorrelationId:
      type: object
      properties:
        correlationId:
          type: string
      title: AsyncCorrelationId
  requestBodies:
    AddressValidationDto:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddressValidationDto'
      description: address
      required: true
    ResourcePatchOptions:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourcePatchOptions'
      description: resourcePatchOptions
      required: true