> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an entitlement using externalEntitlementId

> Get information about an entitlement using external entitlement id.



## OpenAPI

````yaml /openapi/current/dvm/reseller-to-dvm/entitlement/openapi.yaml get /v1/entitlement
openapi: 3.1.0
info:
  title: Entitlements
  version: 1.4.2
  description: >

    # Change log

    **2026-06-02** | v.1.4.2

    - Updated authentication: replaced single Basic Auth scheme with X-API-Key,
      Basic Auth, and OAuth2 (client credentials) security schemes, aligned with
      Reseller Notifications API

    **2025-06-12** | v.1.4.1

    - Overview & change log added


    **2024-09-04** | v.1.4.0

    - Top ups released


    **2023-08-14** | v.1.3.0

    - Added reseller-initiated /activationInfo endpoint

    - Added metadata to error responses to identify whether the error originated
    from Bango or the merchant. This is to help resellers resolve integration
    issues more easily.


    **2022-09-22** | v.1.2.0

    - Added Bango-generated sharedCustomerId to reseller notifications, merchant
    requests and all responses


    **2021-08-05** | v.1.1.0

    - Added extensionData for resellers

    - Added merchantExtensionData for merchants

    - Added financeData to relevant merchant-initiated API requests, reseller
    notifications and all responses

    - Added merchantBangoExtensionData for merchant requests and responses

    - Added externalEntitlementId for resellers


    **2020-11-03** | v.1.0.0

    - Initial release
servers:
  - url: https://resale.api.sandbox.bango.com
    description: Integration test environment
  - url: https://resale.api.bango.com
    description: Production environment
security:
  - XApiKey: []
  - BasicAuth: []
  - OAuth2: []
tags:
  - name: Echo
    description: Check your connection to the Bango resale API
  - name: Entitlement
    description: Manage the lifecycle of your entitlements
  - name: Top Ups
    description: >-
      Top up short-lived entitlements for automated duration extension and
      suspend/terminate flows
paths:
  /v1/entitlement:
    get:
      tags:
        - Entitlement
      summary: Get an entitlement using externalEntitlementId
      description: Get information about an entitlement using external entitlement id.
      operationId: get
      parameters:
        - name: X-RequestIdentifier
          in: header
          description: Optional identifier to support idempotency
          schema:
            type: string
            format: uuid
        - name: ExternalEntitlementId
          in: header
          required: true
          description: Unique identifier provided for the entitlement by the Reseller
          schema:
            type: string
      responses:
        '200':
          description: Entitlement retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementResponse'
              examples:
                OK:
                  value:
                    entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f
                    customerIdentifier: '4407123456789'
                    sharedCustomerId: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e
                    bangoUserId: '2147483647'
                    productKey: BangoMusic
                    entitlementDisplayName: 30 days Bango music
                    offerKey: null
                    merchantAccountKey: BANGO
                    activationCode: null
                    dateCreated: '2020-06-22T17:35:38.92Z'
                    dateActivated: '2020-06-22T17:36:01Z'
                    dateExpiry: '0001-01-01T00:00:00Z'
                    dateAutoSuspend: null
                    dateEnded: '0001-01-01T00:00:00Z'
                    dateFailed: '0001-01-01T00:00:00Z'
                    responseCode: OK
                    responseMessage: Success
                    status: ACTIVE
                    externalEntitlementId: 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63
                    extensionData:
                      additionalProp1: string
                      additionalProp2: string
                      additionalProp3: string
                    parameters: null
                    extraInformation:
                      communicationInformation:
                        emailAddress: 123@abc.co.uk
                        msisdn: '441234567890'
                      clientDevice:
                        type: STB
                        id: bc449c9e-406f-4399-a3ff-8671a27ac410
                        typeId: P49AJFND8NFN23NANGAJG
                        modelName: STB Model X7
                        modelNumber: IAH45IAOF/5
                        serialNumber: JHFJHA43JNFA9393GFD
                        osType: Linux
                        osVersion: 10.3.8
                        macAddress: 4A-0F-99-F2-D3-DD
                        browser: Firefox
                      source:
                        channelType: Website
                        campaignRef: SUMMER_PROMO
                        referrer: SEARCH_ENGINE
                        bundleId: BundleABC123
                        country: United Kingdom
                        region: East Anglia
                        brand: BrandABC
                    financeData:
                      source: Merchant
                      type: order
                      timestamp: '2021-10-18T11:09:44Z'
        '400':
          description: Invalid API request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Invalid API request:
                  value:
                    responseCode: BAD_REQUEST
                    responseMessage: Invalid request.
                    metadata:
                      responseMessageFrom: BANGO
                Not supported:
                  value:
                    responseCode: OPERATION_NOT_SUPPORTED
                    responseMessage: Operation not supported for entitlement route.
                    metadata:
                      responseMessageFrom: BANGO
        '401':
          description: Unauthorized (no response body returned)
        '404':
          description: Entitlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Not found:
                  value:
                    responseCode: NOT_FOUND
                    responseMessage: Entitlement Not Found
                    metadata:
                      responseMessageFrom: BANGO
        '429':
          description: Request limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Too many requests:
                  value:
                    responseCode: TOO_MANY_REQUESTS
                    responseMessage: Request limit reached. Please try again later.
                    metadata:
                      responseMessageFrom: BANGO
        '500':
          description: Unexpected server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                InternalError:
                  value:
                    responseCode: INTERNAL_ERROR
                    responseMessage: null
                    metadata:
                      responseMessageFrom: BANGO
        '503':
          description: Bango Platform undergoing maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseObject'
              examples:
                Service unavailable:
                  value:
                    responseCode: SERVICE_UNAVAILABLE
                    responseMessage: null
                    metadata:
                      responseMessageFrom: BANGO
components:
  schemas:
    EntitlementResponse:
      type: object
      properties:
        entitlementId:
          type: string
          description: Unique identifier representing a specific entitlement
        customerIdentifier:
          type: string
          description: Unique, immutable user identifier
          examples:
            - '123456789'
        sharedCustomerId:
          type: string
          format: uuid
          description: >-
            Bango generated id shared between reseller and merchant for this
            customer (contact support for setup)
          examples:
            - db2001b5-fde5-4654-9ecd-b3b04ba8f025
        merchantAccountKey:
          type: string
          description: Unique identifier for the content provider
          examples:
            - BANGO_US
        productKey:
          type: string
          description: Unique identifier for the product/offer
          examples:
            - MUSIC
        notificationUrl:
          type: string
          format: url
          description: >-
            The endpoint where Bango will send all notifications regarding this
            entitlement
          examples:
            - https://notifications.bango.com
        offerKey:
          type: string
          description: Entitlement offer identifier
          examples:
            - BUNDLE
        externalEntitlementId:
          type: string
          description: >-
            Unique identifier for the entitlement provided by the reseller. If
            the previous attempt to create an entitlement failed, this value can
            be reused.
          examples:
            - 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63
        entitlementDisplayName:
          type: string
          description: Entitlement display name used in reports.
          examples:
            - 30 day free trial for Bango Music
        dateCreated:
          type: string
          format: date
          description: Timestamp for the creation of the entitlement
          examples:
            - '2024-06-22T17:35:38.920Z'
        dateActivated:
          type: string
          format: Date
          description: >-
            Timestamp provided by the content provider when the entitlement is
            activated
          examples:
            - '2024-06-23T17:35:38.920Z'
        dateEnded:
          type: string
          format: date
          description: Timestamp for when the entitlement terminated
          examples:
            - '1901-01-01T00:00:00.000Z'
        dateSuspended:
          type: string
          format: date
          description: Timestamp for when the entitlement was suspended
          examples:
            - null
        dateResumed:
          type: string
          format: date
          description: Timestamp for when the entitlement was last resumed
          examples:
            - null
        dateExpiry:
          type: string
          format: date
          description: >-
            If set, Bango will schedule a termination request to the content
            provider on this date. Date format must be ISO 8601
          examples:
            - '2024-12-05T07:46:52.000Z'
        dateAutoSuspend:
          type: string
          format: date
          description: >-
            If set, Bango will schedule a suspension request to the content
            provider on this date. Date format must be ISO 8601
          examples:
            - '2024-09-05T07:46:52.000Z'
        responseCode:
          type: string
          examples:
            - OK
        responseMessage:
          type: string
          examples:
            - Success
        status:
          type: string
          examples:
            - ACTIVE
          enum:
            - PENDING
            - ACTIVE
            - SUSPENDED
            - ACTIVE-ENDING
            - CANCELLED
            - REVOKED
          description: |
            The entitlement status. Possible values are:
              - PENDING: The entitlement has been initiated, but the user has not yet completed the activation process.
              - ACTIVE: The entitlement has been successfully activated
              - SUSPENDED: The entitlement has been suspended.
              - ACTIVE-ENDING: The entitlement is ending at the end of the current period.
              - CANCELLED: The entitlement has been cancelled.
              - REVOKED: The entitlement has been revoked. 
        activationCode:
          type: string
          description: Code or token used for the entitlement activation
          examples:
            - null
        parameters:
          type: object
          properties:
            Action:
              type: string
              description: The action the reseller should take next
              enum:
                - NAVIGATE_TO_URL
            Url:
              type: string
              description: >-
                The activation url provided by the content provider. Redirect
                the customer to this link to continue the activation process.
              examples:
                - https://activation-link.bango.com
        extensionData:
          $ref: '#/components/schemas/ExtensionData'
          type: object
        extraInformation:
          $ref: '#/components/schemas/ExtraInformation'
          type: object
    ErrorResponseObject:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
    ExtensionData:
      type: object
      description: Custom key value pairs
      properties:
        customField1:
          type: string
          examples:
            - value1
        customField2:
          type: string
          examples:
            - value2
    ExtraInformation:
      type: object
      properties:
        communicationInformation:
          $ref: '#/components/schemas/CommunicationInformation'
        clientDevice:
          $ref: '#/components/schemas/ClientDevice'
        source:
          $ref: '#/components/schemas/Source'
    Metadata:
      type: object
      properties:
        responseMessageFrom:
          type: string
          description: The originator of the error (either Bango or the content provider)
          enum:
            - BANGO
            - MERCHANT
    CommunicationInformation:
      type: object
      properties:
        msisdn:
          type: string
          examples:
            - '441234567890'
        emailAddress:
          type: string
          examples:
            - example@bango.com
    ClientDevice:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - STB
            - MOBILE
            - DESKTOP
            - TABLET
          description: >-
            The type of device. This field is mandatory if clientDevice is being
            provided
          examples:
            - STB
        id:
          type: string
          description: The unique id of the device
          examples:
            - bc449c9e-406f-4399-a3ff-8671a27ac410
        typeId:
          type: string
          description: The common id for the type of device
          examples:
            - P49AJFND8NFN23NANGAJG
        modelName:
          type: string
          description: The model name of the device
          examples:
            - STB Model X7
        modelNumber:
          type: string
          description: The model number of the device
          examples:
            - IAH45IAOF/5
        serialNumber:
          type: string
          description: The serial number of the device
          examples:
            - JHFJHA43JNFA9393GFD
        osType:
          type: string
          description: The operating system of the device
          examples:
            - Linux
        osVersion:
          type: string
          description: The version of the operating system of the device
          examples:
            - 10.3.8
        macAddress:
          type: string
          description: The MAC address of the device
          examples:
            - 4A-0F-99-F2-D3-DD
        browser:
          type: string
          description: The browser being used
          examples:
            - Chrome
    Source:
      type: object
      properties:
        channelType:
          type: string
          enum:
            - Retail
            - SMS
            - App
            - Website
            - Email
            - Call Centre
            - Mobile
            - Set Top Box
            - Other
          description: The channel the customer used to get the offer
          examples:
            - Retail
        campaignRef:
          type: string
          description: The reference of the campaign that attracted the customer
          examples:
            - SUMMER_PROMO
        referrer:
          type: string
          description: The origin of the customer's request
          examples:
            - SEARCH_ENGINE
        bundleId:
          type: string
          description: Identifies the bundle the entitlement is part of
          examples:
            - BundleABC123
        country:
          type: string
          description: The customer's country
          examples:
            - United Kingdom
        region:
          type: string
          description: The customer's regional area or code
          examples:
            - CB1 3ED
        brand:
          type: string
          description: The brand
          examples:
            - BrandA
  securitySchemes:
    XApiKey:
      type: apiKey
      in: header
      name: x-api-key
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      description: >
        Bango uses
        https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/.

        Please note that when requesting a token, we only support the option to
        send the client secret in the request body
      flows:
        clientCredentials:
          tokenUrl: https://auth.bango.com/oath2/token
          scopes:
            any: >-
              grants Bango access to the merchant system based on merchant
              defined rules

````