openapi: 3.0.3
info:
  title: Vonage Device Status API
  description: >
    The Device Status API enables obtaining network information such as roaming
    and connectivity statuses of 

    a network-connected device.


    > Please note that this API is not currently publicly available. If you wish
    to get access, please contact our sales or support team using [this
    form](https://www.vonage.com/communications-apis/contact-api/).
  termsOfService: https://www.vonage.com/legal/communications-apis/terms-of-use/
  contact:
    name: Vonage Developer Relations
    email: devrel@vonage.com
    url: https://developer.vonage.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.5.0-rc-a1
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/
servers:
  - url: https://api-eu.vonage.com/camara/device-status/v050
paths:
  /connectivity:
    post:
      tags:
        - Device connectivity status
      summary: Get the connectivity status information
      security:
        - three_legged_connectivity:
            - dpv:NotApplicable#device-status:connectivity:read
      description: Get the current connectivity status information
      operationId: getConnectivityStatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceStatus"
        required: true
      responses:
        "200":
          description: Contains information about current connectivity status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectivityStatusResponse"
              examples:
                Connected-With-SMS:
                  value:
                    connectivityStatus: CONNECTED_SMS
                Connected-With-DATA:
                  value:
                    connectivityStatus: CONNECTED_DATA
                Not-Connected:
                  value:
                    connectivityStatus: NOT_CONNECTED
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "502":
          $ref: "#/components/responses/Generic502"
  /roaming:
    post:
      tags:
        - Device roaming status
      summary: Get the roaming status and the country information
      security:
        - three_legged_roaming:
            - dpv:NotApplicable#device-status:roaming:read
      description: Get the current roaming status and the country information
      operationId: getRoamingStatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceStatus"
        required: true
      responses:
        "200":
          description: Contains information about current roaming status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoamingStatusResponse"
              example:
                $ref: "#/components/examples/DEVICE_ROAMING_STATUS"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "502":
          $ref: "#/components/responses/Generic502"
components:
  securitySchemes:
    three_legged_roaming:
      type: oauth2
      description: >
        Three-legged OAuth 2.0 flows require the application to obtain End-User
        authorization and a token to access resources on behalf of the End-User.
        More information at
        <https://developer.vonage.com/concepts/guides/authentication>.


        API specs available at: <https://developer.vonage.com/api/camara/auth>.
      flows:
        authorizationCode:
          authorizationUrl: https://api-eu.vonage.com/oauth2/bc-authorize
          tokenUrl: https://api-eu.vonage.com/oauth2/token
          scopes:
            dpv:NotApplicable#device-status:roaming:read: Get roaming status
    three_legged_connectivity:
      type: oauth2
      description: >
        Three-legged OAuth 2.0 flows require the application to obtain End-User
        authorization and a token to access resources on behalf of the End-User.
        More information at
        <https://developer.vonage.com/concepts/guides/authentication>.


        API specs available at: <https://developer.vonage.com/api/camara/auth>.
      flows:
        authorizationCode:
          authorizationUrl: https://api-eu.vonage.com/oauth2/bc-authorize
          tokenUrl: https://api-eu.vonage.com/oauth2/token
          scopes:
            dpv:NotApplicable#device-status:connectivity:read: Get connectivity status
  schemas:
    RoamingStatusResponse:
      type: object
      required:
        - roaming
      properties:
        roaming:
          $ref: "#/components/schemas/ActiveRoaming"
        countryCode:
          $ref: "#/components/schemas/CountryCode"
        countryName:
          $ref: "#/components/schemas/CountryName"
    ActiveRoaming:
      description: Roaming status. True, if it is roaming
      type: boolean
    ConnectivityStatusResponse:
      type: object
      required:
        - connectivityStatus
      properties:
        connectivityStatus:
          $ref: "#/components/schemas/ConnectivityStatus"
    ConnectivityStatus:
      description: |
        CONNECTED_DATA: The device is connected to the network for Data usage

        CONNECTED_SMS: The device is connected to the network for SMS usage

        NOT_CONNECTED: The device is not connected
      type: string
      enum:
        - CONNECTED_DATA
        - CONNECTED_SMS
        - NOT_CONNECTED
    Device:
      description: >
        End-user equipment able to connect to a mobile network. Examples of
        devices include smartphones or IoT sensors/actuators.
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
      minProperties: 1
    PhoneNumber:
      type: string
      pattern: ^\+?[0-9]{5,15}$
      example: "123456789"
      description: A public identifier addressing a telephone subscription. In mobile
        networks it corresponds to the MSISDN (Mobile Station International
        Subscriber Directory Number). In order to be globally unique it has to
        be formatted in international format, according to E.164 standard,
        optionally prefixed with '+'.
    CountryCode:
      description: The Mobile country code (MCC) as an geographic region identifier
        for the country and the dependent areas.
      type: integer
    CountryName:
      description: The ISO 3166 ALPHA-2 country-codes of mapped to mobile country
        code(MCC). If there is mapping of one MCC to multiple countries, then we
        have list of countries. If there is no mapping of MCC to any country,
        then an empty array [] shall be returned..
      type: array
      items:
        type: string
    DeviceStatus:
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"
      required:
        - device
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    Generic401:
      description: Authentication problem with the client request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 401
            code: UNAUTHENTICATED
            message: Request not authenticated due to missing, invalid, or expired
              credentials
    Generic403:
      description: Client does not have sufficient permission
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 403
            code: PERMISSION_DENIED
            message: Client does not have sufficient permissions to perform this action
    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 404
            code: NOT_FOUND
            message: The specified resource is not found
    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 409
            code: CONFLICT
            message: The specified resource is in a conflict
    Generic502:
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 502
            code: INTERNAL
            message: Bad Gateway
  examples:
    DEVICE_ROAMING_STATUS:
      roaming: true
      countryCode: 262
      countryName:
        - DE
