webrtc-call-handling.yaml

openapi: 3.0.3
info:
  title: WebRTC Call Handling
  description: |-
    # Introduction

    This API provides REST API for clients to manage live audio and video sessions
    towards the operator's network (IMS network).

    To handle audio/video sessions, what we usually known as *calls*, the network
    requires to identify both involved parties: caller, the origin, and the callee,
    the destination. Once the involved communication endpoints are identified,
    the endpoints need to negotiate *how* to send media from one endpoint to the other.

    The first step, *identify the endpoints* is handled through
    parameters in the API request. The latter step, *negotiate how to connect*, is done by
    sharing media transmission requirements (called SDP information) between the involved endpoints.

    In this step, the WebRTC technology is used to simplify the access to the
    media, and get a simple and well-known protocol to negotiate the media transmission
    requirements.

    Let's dig into more details on section 3: API functionality

    **Use cases to cover:**
      - Functional:
        - Ability to create audio and video sessions on the network, this grants
          ability to reach any phone number on the public network using your telco
          provider rights.
        - Ability to retrieve any session, to recover for a network disconnection
          or to check current status for any reason.
        - Ability to upgrade to video, change sending audio/video parameters, or
          notify the network about any modification on your side of the calls.
        - Ability to hangup the call. Stop the transmission, and delete your audio
          and video session.
      - An additional subscription to webrtc-events-subscriptions API is required to receive
        incoming events from network side (ex. remote hangup event).

    # Relevant terms and definitions

    - **media session**: An exchange of media between devices.
      Typical example of session is a "single one-to-one call".
    - **mediaSessionId**: Unique identifier of a **media session** using
      webrtc-call-handling API. Retrieved using the `webrtc-call-handling` API
    - **deviceId**: A unique identifier for the physical device where a media
      session is initiated. It is provided by the WebRTC application, it remains
      consistent across multiple installations or logins on the same device. Its
      primary function is to ensure that only one WebRTC session (**registration**)
      is active per device at a time, enabling the network to clean up any stale
      sessions if a new session is initiated on the same device.
    - **registration**: A device status in which the device is properly
      identified and recognized as reachable by the server side of the network.
    - **registrationId**: Unique identifier of an device **registration**.
      Retrieved using the `webrtc-registration` API
    - **x-correlator**: Unique ID included in the API request created by the API consumer.
      It is used to correlate an API request with its response and help in debugging.
    - **WebRTC**: WebRTC is a free and open-source project providing web browsers
      and mobile applications with real-time communication via application programming
      interfaces. It allows audio and video communication and streaming to work
      inside web pages by allowing direct peer-to-peer communication
    - **SDP**: Acronym for Session Description Protocol. The SDP is a format for
      describing multimedia communication sessions for the purposes of announcement
      and invitation.
    - **WrtcSdpDescriptor**: Schema to include inside a JSON, a SDP body. You can
      obtain an SDP for WebRTC calling using the WebRTC API provided by the browser
      or any other media library.

    # API functionality

    This API allows to create 1-1 voice and video sessions. These, identified by a
    unique `mediaSessionId` can be recovered, updated and terminated via this API
    and its methods.
    - **POST**: Create a new session using a valid `registrationId` from registration API
    - **GET**: Recover an existing session via its unique `mediaSessionId`
    - **DELETE**: Finish an existing session via its unique `mediaSessionId`
    - **PUT**: Update the status of a session via its unique `mediaSessionId`

    To receive updates from the network about the session establishment process, you
    must use `webrtc-events-subscriptions` API.

    ## 1. Creating a call

    To call someone, you need, previously a valid registration on the network.
    You must check the webrtc-registration API to retrieve a valid registration
    on the network that allows you to send calls (IMS registration).

    Once this is completed, you can consume the POST /sessions/ endpoint to call
    a remote destination.

    ```
    POST /webrtc-call-handling/v0.2/sessions
    {
      "originatorAddress": "tel:+17085852753",
      "receiverAddress": "tel:+17085854000",
    }
    ```

    This will create a call, but without local media you will have a problem, or
    maybe the network will reject your call. You need to add a local SDP offer.

    > **The WebRTC SDP local candidate**
    >
    > What is usually done, before attempt to create a call, is to solve the SDP local
    description. This is, how you are going to send the media. To explain it briefly,
    browsers offer the
    [WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) that
    include `getUserMedia()` and `RTCPeerConnection` interfaces that will simplify
    the process.
    >
    > In summary, we need to obtain the media, create the `RTCPeerConnection`
    and use it's SDP on our CAMARA webrtc-call-handling API as the offer. There
    is extra information about this concept on the SupportingDocuments folder.

    Once you retrieve you local SDP offer, you modify your session including it,
    or maybe you prefer to solve the local candidate before attempt the call, in
    that case, you will include your local offer on the audio/video session creation.

    ```
    POST /webrtc-call-handling/v0.2/sessions
    {
        "originatorAddress": "tel:+17085852753",
        "receiverAddress": "tel:+17085854000",
        "offer": {
            "sdp": "v=0\r\no=- 4808447918291752114 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\nm=audio 13765 UDP/TLS/RTP/SAVPF 111 63 9 0 8 13 110 126\r\nc=IN IP4 123.123.123.123\r\na=ice-ufrag:YoUo\r\na=ice-pwd:kK5J6IAgiKFDFU+2rC+FyZal\r\n...\r\n"
            }
    }
    ```

    Following this point, your call is progressing and the network will inform
    about extra information required and connection status via de the
    webrtc-events-subscriptions API.

    Check webrtc-events-subscriptions API inline documentation and supporting documents
    for further information.

    ## 2. Hanging up a call

    When you have a voice/video session in progress, you can decide to finish the
    call, to do so, simply execute a DELETE request of the session using the
    `mediaSessionId` obtained on call creation.

    This action will trigger all necessary action on the network side to properly
    hangup and drop the call.

    ## 3. Picking up a call

    Using the `webrtc-events-subscriptions` API, you can receive events from the network, these
    events could include the `session-invitation` event. This means that someone
    is calling you.

    To *hook off*, we need to retrieve the session based on the `mediaSessionId`
    using the GET request, afterwards, you can present to the user some
    confirmation option to accept the call.

    Final step is to include a local offer. We already seen at 3.1 that a local
    SDP is required, in this case, we will use the PUT request to modify the
    audio/video session and include the information about the responding device.

    Let's say that we are responding this session `0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD`:
    ```
    PUT /webrtc-call-handling/v0.2/sessions/0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD/status
    {
        "status": "InProgress",
        "answer": {
            "sdp": "v=0\r\no=- 4808447918291752114 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\nm=audio 13765 UDP/TLS/RTP/SAVPF 111 63 9 0 8 13 110 126\r\nc=IN IP4 123.123.123.123\r\na=ice-ufrag:YoUo\r\na=ice-pwd:kK5J6IAgiKFDFU+2rC+FyZal\r\n...\r\n"
            }
    }
    ```

    # Additional CAMARA error responses
    The list of error codes in this API specification is not exhaustive.
    Therefore the API specification may not document some non-mandatory error
    statuses as indicated in `CAMARA API Design Guide`.

    Please refer to the `CAMARA_common.yaml` of the Commonalities Release
    associated to this API version for a complete list of error responses. The
    applicable Commonalities Release can be identified in the `API Readiness
    Checklist` document associated to this API version.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible
    error response if it is explicitly documented in the API.

    # Located calls

    As part of the extended, or contextual information of calls, a location can
    be provided as part of the call information. Any party **MAY** provide a
    `locationDetails` object to share the geographic position of their device,
    in support of security, routing, or any other use case provided by the network.

    The `locationDetails` field in `MediaSessionInformation` always represents the
    location of the party making the request:
    - In `POST /sessions`, it is the originator's device location.
    - In `PUT /sessions/{mediaSessionId}/status`, it is the location of the party
    making the update (originator or answering party).

    The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229,
    RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape.

    # Emergency Calling

    - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`.
    - When `callType` is `EMERGENCY`, the client **MAY** include
    `locationDetails` describing the caller's device location.
    - The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229,
    RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape.
    - If `callType` is omitted, it defaults to `REGULAR`.

    # Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an
    API consumer requests an access token. Please refer to Identity and Consent
    Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
    for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the
    onboarding process, happening between the API consumer and the API provider,
    taking into account the declared purpose for accessing the API, whilst also
    being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal data is processed by the API and users can exercise
    their rights through mechanisms such as opt-in and/or opt-out, the use of
    three-legged access tokens is mandatory. This ensures that the API remains
    in compliance with privacy regulations, upholding the principles of
    transparency and user-centric privacy-by-design.

  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
  version: wip
  x-camara-commonalities: 0.6

externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/WebRTC
servers:
  - url: '{apiRoot}/webrtc-call-handling/vwip'
    variables:
      apiRoot:
        description: API root
        default: 'http://localhost:9091'
tags:
  - name: Call handling
    description: Operations to manage voice video sessions (calls)
paths:
  /sessions:
    post:
      tags:
        - Call handling
      summary: Creates voice and/or video session
      description: Creates a voice and/or video session
      operationId: createSession
      parameters:
        - $ref: "#/components/parameters/x-correlator"
        - $ref: '#/components/parameters/hdrRegistrationId'
      security:
        - openId:
            - webrtc-call-handling:sessions:create
      requestBody:
        description: Provide the information required for session creation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaSessionCreate'
            examples:
              RegularMediaSessionRequest:
                $ref: '#/components/examples/exampleRegularMediaSessionRequest'
              EmergencyMediaSessionRequest:
                $ref: '#/components/examples/exampleEmergencyMediaSessionRequest'
              LocatedMediaSessionRequest:
                $ref: '#/components/examples/exampleLocatedMediaSessionRequest'
      responses:
        '201':
          description: Created
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaSessionResponse'
              examples:
                SessionCreated:
                  $ref: '#/components/examples/exampleMediaSessionResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: "#/components/responses/Generic401"
        '403':
          $ref: '#/components/responses/Generic403'
        '501':
          description: Not Implemented
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorInfo'
                  - type: object
                    properties:
                      status:
                        enum:
                          - 501
                      code:
                        enum:
                          - CALLTYPE_EMERGENCY_NOT_SUPPORTED
              examples:
                501_CALLTYPE_EMERGENCY_NOT_SUPPORTED:
                  description: The implementation of API provider does not support the `callType` of `EMERGENCY`.
                  value:
                    status: 501
                    code: CALLTYPE_EMERGENCY_NOT_SUPPORTED
                    message: Server does not support call type EMERGENCY.
  /sessions/{mediaSessionId}:
    get:
      tags:
        - Call handling
      summary: Get the media session information
      description: |
        Get the media Session description based on `mediaSessionId`.

        ** The client shall construct the API path using the `mediaSessionId` supplied
        in the session creation response (origination) or in the invitation notification
        (termination). **
      operationId: getSessionDetailsById
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: '#/components/parameters/pathParamMediaSessionId'
      security:
        - openId:
            - webrtc-call-handling:sessions:read
      responses:
        '200':
          description: A session information
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaSessionResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
    delete:
      tags:
        - Call handling
      summary: Cancel or Terminate the media session
      description: >
        Cancel a 1-1 media session (as originator),

        Decline a 1-1 media session (as receiver),

        Terminate a 1-1 an ongoing media session

        ** The client shall construct the API path using the mediaSessionId supplied in the session creation response (origination) or in the invitation notification (termination). **'
      operationId: deleteSessionById
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: '#/components/parameters/pathParamMediaSessionId'
      security:
        - openId:
            - webrtc-call-handling:sessions:delete
      responses:
        '204':
          description: Session deleted
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
  /sessions/{mediaSessionId}/status:
    put:
      tags:
        - Call handling
      summary: Update the status of the media session
      description: |
        Update the status of the media session, this may include updating SDP media

        The API consumer shall construct the API path using the `mediaSessionId` supplied in the session creation response (origination) or in the invitation notification (termination).

        The party making the update MAY include `locationDetails` to share their device location. When included in an answer/accept step (e.g., status `Connected` with an answer SDP), `locationDetails` describes the answering party's device location. After call establishment, either party MAY provide or update their location by including `locationDetails`; in that case, the provided location applies to the party making the update.
      operationId: updateSessionStatus
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: '#/components/parameters/pathParamMediaSessionId'
      security:
        - openId:
            - webrtc-call-handling:sessions:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaSessionStatusChange'
            examples:
              Update connected (call is established with SDP answer):
                $ref: '#/components/examples/exampleStatusChangeConnected'
              Update ringing (status update without SDP):
                $ref: '#/components/examples/exampleStatusChangeRinging'
              Answer with location (callee accepts and shares location):
                $ref: '#/components/examples/exampleSessionStatusConnectedWithLocation'
              Location update (post-setup location sharing):
                $ref: '#/components/examples/exampleSessionStatusLocationUpdate'
      responses:
        '200':
          description: |
            Updated the session status (with SDP data).
            It will confirm the status defined on the PUT operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaSessionResponse'
              examples:
                Update inProgress (update media candidates):
                  $ref: '#/components/examples/exampleSessionStatus183InProgress'
                Update ringing (device user endpoint is ringing):
                  $ref: '#/components/examples/exampleSessionStatus180Ringing'
                Update connected (call is established):
                  $ref: '#/components/examples/exampleSessionStatus200Connected'
                Update hold (call has been placed on call waiting mode):
                  $ref: '#/components/examples/exampleSessionStatusHold'
                Update resume (call has been resumed):
                  $ref: '#/components/examples/exampleSessionStatusResume'
                Answer with location (callee accepts and shares location):
                  $ref: '#/components/examples/exampleSessionStatusConnectedWithLocation'
                Location update (post-setup location sharing):
                  $ref: '#/components/examples/exampleSessionStatusLocationUpdate'
        '204':
          description: Updated the session status (no content)
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
components:
  securitySchemes:
    openId:
      type: openIdConnect
      description: OpenID Connect authentication via discovery metadata.
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  parameters:
    hdrRegistrationId:
      name: registrationId
      in: header
      description: The device registration identifier assigned by the network
      required: true
      style: simple
      explode: false
      schema:
        type: string
        maxLength: 256
    pathParamMediaSessionId:
      name: mediaSessionId
      in: path
      description: The sessionId assigned by the network for the media session
      required: true
      style: simple
      explode: false
      schema:
        type: string
        maxLength: 256
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  schemas:
    XCorrelator:
      description: Correlator string, UUID format recommended but any string matching the pattern can be used
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      maxLength: 256
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    MediaSessionInformation:
      description: Information about a WebRTC media session including originator and receiver identities, SDP offer/answer, and call status
      type: object
      properties:
        originatorAddress:
          $ref: '#/components/schemas/Address'
        originatorName:
          type: string
          maxLength: 256
          description: Friendly name of the call originator
          example: 'Alice'
        receiverAddress:
          $ref: '#/components/schemas/Address'
        receiverName:
          type: string
          maxLength: 256
          description: Friendly name of the call terminator
          example: 'Bob'
        status:
          $ref: '#/components/schemas/SessionStatus'
        offer:
          $ref: '#/components/schemas/WrtcSdpDescriptor'
        answer:
          $ref: '#/components/schemas/WrtcSdpDescriptor'
        callType:
          type: string
          description: Type of call. When set to EMERGENCY, the client MAY provide locationDetails. If omitted, treated as REGULAR.
          enum:
            - REGULAR
            - EMERGENCY
        locationDetails:
          description: >-
            Location of the party making this request. When provided in `POST /sessions`, it represents the originator's device location.
            When provided in `PUT /sessions/{mediaSessionId}/status`, it represents the location of the party making the update
            (either originator or answering party). Providing this information is specific to certain use cases and does not imply a
            guarantee of any particular server-side action or behavior.
          allOf:
            - $ref: '#/components/schemas/LocationDetails'
    MediaSessionCreate:
      description: Request body for creating a main session (POST request)
      allOf:
        - $ref: '#/components/schemas/MediaSessionInformation'
        - type: object
          required:
            - originatorAddress
            - receiverAddress
            - offer
    MediaSessionResponse:
      description: Representation of a media session resource (POST/PUT/GET response)
      type: object
      required:
        - originatorAddress
        - receiverAddress
        - status
        - offer
        - mediaSessionId
      allOf:
        - $ref: '#/components/schemas/MediaSessionInformation'
        - type: object
          properties:
            mediaSessionId:
              type: string
              maxLength: 256
              description: >-
                The media session ID created by the network.
              example: 0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF
    MediaSessionStatusChange:
      description: Request body for updating the status of a media session (PUT request)
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/SessionStatus'
        offer:
          $ref: '#/components/schemas/WrtcSdpDescriptor'
        answer:
          $ref: '#/components/schemas/WrtcSdpDescriptor'
        locationDetails:
          $ref: '#/components/schemas/LocationDetails'
    WrtcSdpDescriptor:
      type: object
      description: |-
        **OFFER**: An inlined session description in SDP format [RFC4566].If XML syntax
        is used, the content of this element SHALL be embedded in a CDATA
        section.

        **ANSWER**: This type represents an answer in WebRTC Signaling. This element is not
        present in case there is no answer yet, or the session invitation has
        been declined by the Terminating Participant.This element MUST NOT be
        present in a request from the application to the server to create a
        session.
      properties:
        sdp:
          type: string
          maxLength: 65536
          description: |-
            An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section
    SessionStatus:
      type: string
      description: Provides the status of the media session. During the session creation, this attribute SHALL NOT be included in the request.
      enum:
        - Initial
        - InProgress
        - Ringing
        - Proceeding
        - Connected
        - Terminated
        - Hold
        - Resume
        - SessionCancelled
        - Declined
        - Failed
        - Waiting
        - NoAnswer
        - NotReachable
        - Busy
      example: Ringing
    ErrorInfo:
      description: A structured error response providing details about a failed request, including the HTTP status code, an error code, and a human-readable message
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          format: int32
          minimum: 100
          maximum: 599
          description: HTTP response status code
        code:
          type: string
          maxLength: 96
          description: Friendly Code to describe the error
        message:
          type: string
          maxLength: 512
          description: A human readable description of what the event represent
    Address:
      type: string
      description: >-
        Subscriber address (Sender or Receiver).
        The following formats are supported:
        - A TEL URI :
          - an international format; or
          - a home local number (as defined in 3GPP TS 24.229 subclause 5.1.2A.1.5) qualified by a `phone-context`
            parameter identifying the home network numbering plan.
        - A SIP URI :
          - SIP URI with a generic user part;
          - SIP URI with a home local number (`user=phone`). The user part MAY contain a home local number qualified by
            a `phone-context` parameter, in which case the `user=phone` URI parameter SHALL be appended;
          - an emergency service URN; or
          - anonymous SIP URI

        The reserved value `sip:anonymous@anonymous.invalid` (as defined in RFC 3323) MAY be used to indicate
        that the calling party identity is withheld within the trust domain. When `sip:anonymous@anonymous.invalid` is set
        as the `originatorAddress`, the session SHALL be handled as an anonymous call origination.
        This value SHALL NOT be used as the `receiverAddress`.

      pattern: '^(tel:\+[1-9][0-9]{4,14}|tel:[0-9*#]{1,15};phone-context=(?:\+[1-9][0-9]{0,14}|[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?)+)|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|sip:[0-9*#]{1,15};phone-context=(?:\+[1-9][0-9]{0,14}|[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?)+)@[A-Za-z0-9.-]+\.[A-Za-z]{2,};user=phone|urn:service:sos(?:\.[a-z0-9](?:[a-z0-9\-]{0,30}[a-z0-9])?)*|sip:anonymous@anonymous\.invalid)$'
      example: 'tel:+11234567899'
      maxLength: 256
    LocationDetails:
      type: object
      description: >-
        Details about a party's location and related information. This object adheres to
        3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO compatibility.
        Providing this information is specific to certain use cases and does not imply a
        guarantee of any particular server-side action or behavior.
      properties:
        shape:
          type: string
          enum:
            - Circle
            - Ellipsoid
          description: The shape representing the caller's location (Circle or Ellipsoid).
        coordinates:
          oneOf:
            - $ref: '#/components/schemas/CircleCoordinates'
            - $ref: '#/components/schemas/EllipsoidCoordinates'
          description: The coordinates of the caller's location, specific to the chosen
            shape.
        method:
          type: string
          enum:
            - GPS
            - DBH
            - DBH_HELO
            - Other
          description: 'The method used to obtain the location information.

            * **GPS:** Global Positioning System (highly accurate)
            * **DBH:** Device-Based Hybrid
            * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location
            * **Other:** Other methods (e.g., landmarks, IP Based etc.)

            '
        confidence:
          type: object
          description: The confidence level of the location information.
          properties:
            pdf:
              type: string
              enum:
                - normal
                - uniform
              description: The probability density function (PDF) associated with the
                confidence value.
            value:
              type: number
              minimum: 0
              maximum: 100
              description: The confidence value (percentage).
        timestamp:
          type: string
          format: date-time
          maxLength: 64
          description: The timestamp (in ISO 8601 format) indicating when the location
            information was Calculated. \nThis is crucial for emergency services to
            assess the timeliness of the data. if not provided current timestamp will
            be used by default"
    CircleCoordinates:
      description: Geographic coordinates defining a circular area by center point and radius
      type: object
      required:
        - latitude
        - longitude
        - radius
      properties:
        latitude:
          type: number
          format: float
          description: Latitude of the center point in decimal degrees (WGS84).
        longitude:
          type: number
          format: float
          description: Longitude of the center point in decimal degrees (WGS84).
        radius:
          type: number
          format: float
          description: Radius of the circle in meters, indicating the uncertainty.
    EllipsoidCoordinates:
      description: Geographic coordinates defining an ellipsoidal uncertainty area in the WGS84 geocentric coordinate system
      type: object
      required:
        - latitude
        - longitude
        - zAxis
        - semiMajorAxis
        - semiMinorAxis
        - verticalAxis
        - orientation
      properties:
        latitude:
          type: number
          format: float
          description: Latitude in the WGS 84 geocentric coordinate system.
        longitude:
          type: number
          format: float
          description: Longitude in the WGS 84 geocentric coordinate system.
        zAxis:
          type: number
          format: float
          description: Altitude (optional) in the WGS 84 geocentric coordinate system.
        semiMajorAxis:
          type: number
          description: Length of the semi-major axis of the ellipsoid in meters.
        semiMinorAxis:
          type: number
          description: Length of the semi-minor axis of the ellipsoid in meters.
        verticalAxis:
          type: number
          description: Length of the vertical axis of the ellipsoid in meters.
        orientation:
          type: number
          description: Orientation of the ellipsoid in degrees.
  examples:
    exampleRegularMediaSessionRequest:
      summary: Regular call initiation with media information
      description: Example of a standard outbound call request body with SDP offer
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
    exampleMediaSessionResponse:
      description: Example response body returned after successfully creating a media session
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
        status: Initial
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
    exampleStatusChangeConnected:
      summary: Confirm session is established and provide the SDP answer
      description: Example request body used to confirm that the media session is connected and to provide the SDP answer
      value:
        status: Connected
        answer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
    exampleStatusChangeRinging:
      summary: Notify that the receiver endpoint is ringing
      description: Example request body used to notify that the receiver endpoint is ringing
      value:
        status: Ringing
    exampleSessionStatus183InProgress:
      description: Session status update indicating the call is in progress (183 Session Progress)
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: InProgress
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
        answer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
    exampleSessionStatus180Ringing:
      description: Session status update indicating the remote end is ringing (180 Ringing)
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: Ringing
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
    exampleSessionStatus200Connected:
      description: Session status update indicating the call has been answered and connected (200 OK)
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: Connected
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
        answer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
    exampleSessionStatusHold:
      description: Session status update indicating the call has been placed on hold
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: Hold
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
        answer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
    exampleSessionStatusResume:
      description: Session status update indicating a held call has been resumed
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: Resume
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
        answer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
    exampleSessionStatusConnectedWithLocation:
      summary: Answering party accepts the call and shares their device location
      description: Session status update for a connected call where the answering party shares device location
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: Connected
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
        answer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
        locationDetails:
          shape: Circle
          coordinates:
            latitude: 40.7128
            longitude: -74.0060
            radius: 50
          method: GPS
          confidence:
            pdf: normal
            value: 88
          timestamp: '2025-10-06T19:32:10Z'
    exampleSessionStatusLocationUpdate:
      summary: Post-setup location update by either party
      description: Session status update carrying a location update from either call party after the session is established
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'tel:+17085854000'
        receiverName: Bob
        status: Connected
        offer:
          sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
        mediaSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
        locationDetails:
          shape: Circle
          coordinates:
            latitude: 40.7148
            longitude: -74.0075
            radius: 30
          method: GPS
          confidence:
            pdf: normal
            value: 95
          timestamp: '2025-10-06T19:45:00Z'
    exampleEmergencyMediaSessionRequest:
      summary: Emergency call initiation with location details
      description: Example request body for initiating an emergency call with caller location details
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: 'urn:service:sos'
        receiverName: PSAP
        offer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
        callType: EMERGENCY
        locationDetails:
          shape: Circle
          coordinates:
            latitude: 47.6062
            longitude: -122.3321
            radius: 35
          method: GPS
          confidence:
            pdf: normal
            value: 92
          timestamp: '2025-10-06T19:31:25Z'
    exampleLocatedMediaSessionRequest:
      summary: Regular call initiation with location details
      description: Example request body for a regular call that includes caller location details
      value:
        originatorAddress: 'tel:+17085852753'
        originatorName: Alice
        receiverAddress: tel:+17085854000
        receiverName: Bob
        offer:
          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\n [...]"
        locationDetails:
          shape: Circle
          coordinates:
            latitude: 47.5124
            longitude: -122.4176
            radius: 27
          method: GPS
          confidence:
            pdf: normal
            value: 97
          timestamp: '2025-10-06T19:31:25Z'
  responses:
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  code:
                    enum:
                      - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
                      - INVALID_TOKEN_CONTEXT
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: "originator info is not consistent with access token."
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
                      - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: Some identifier cannot be matched to a device
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Device identifier not found.