.. index:: Advertisement, AdvertisementFeatures, UpcallConfirmations

.. _upcall_confirmations:

Upcall confirmations
====================

You can confirm an advertisement upcall by performing a POST against the upcall confirmations controller resource.

Confirming advertisement upcalls is currently restricted to clients authenticating with client credentials.
These clients should use a token that has the ``confirm_upcall`` scope. Read more about this in the
:ref:`Obtaining an Access Token for a client` section of the authentication chapter.

.. note::
    Work in Progress

Fields
------

.. apifields::

    .. apifield::
        :name: callerPhoneNumber
        :type: string
        :constraints: --
        :required: true
        :writable: false
        :updateable: false
        :description: The phone number of the caller.

    .. apifield::
        :name: calleePhoneNumber
        :type: string
        :constraints: --
        :required: true
        :writable: false
        :updateable: false
        :description: The phone number which has been called.

    .. apifield::
        :name: startTime
        :type: ISO 8601 timestamp
        :constraints: --
        :required: true
        :writable: false
        :updateable: false
        :description: Time when the call started.

    .. apifield::
        :name: endTime
        :type: ISO 8601 timestamp
        :constraints: --
        :required: true
        :writable: false
        :updateable: false
        :description: Time when the call ended.

Reference
---------

.. endpoint:: POST /v1/advertisements/{itemId}/upcall-confirmations

Confirm an advertisement upcall.

Example
-------

.. include:: examples/upcall-confirmations-example.rst

Errors
------

.. errors::

    .. error::
        :http: 404
        :code: advertisement-not-found
        :description: The advertisement with the provided itemId does not exist.

    .. error::
        :http: 403
        :code: unauthorized
        :description: The action you are trying to perform is not allowed.

    .. error::
        :http: 500
        :code: internal-server-error
        :description: Oops! Sorry, something went wrong on our side.