Location Permits
----------------

This API allows listing, retrieving, creating, updating,
and deleting of Location Permits, as well as associating them to locations and users.

Permits required for a location can be set via the ``/location`` endpoint, as described in :ref:`associate-permit-to-location`.

Location Permits held by users can be set via the ``/user`` endpoint, described in :ref:`associate-location-permit-to-user`.


.. warning::
  The endpoints described in this page are only accessible if the
  ``location_access_permits`` toggle has been enabled.


List Location Permits
.....................

.. http:get:: /permit/

   List all permits.

   **Sample request**:

   .. sourcecode:: http

      GET /permit/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "count": 100,
        "items": [
          {
            "name": "Safety Permit",
            "uuid": "d6d22438096503fe72a7c161201c9373",
            "archived": false,
          },
          {
            "name": "Police vetting",
            "uuid": "28a01f359aabafb4ff28347bddd9a24f",
            "archived": false,
          },
          {
            "name": "Security Certification",
            "uuid": "6a360274f3fa2e224e17ba9ece3f4b0a"
            "archived": true,
          }
        ],
        "page": 0,
        "pageSize": 3,
        "sortedBy": []
      }

   :query sortedBy: Available sorting criteria: ``name``
   :query name: A filtering value for permit name
   :query archived: filtered by ``archived``


Get Location Permit
...................

.. http:get:: /permit/(permit_ref)

   Retrieve a given Location Permit.

   **Sample request**:

   .. sourcecode:: http

      GET /permit/d6d22438096503fe72a7c161201c9373 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "name": "Security Certification",
        "uuid": "d6d22438096503fe72a7c161201c9373".,
        "archived": false
      }


Create Location Permit
......................

.. http:post:: /permit/

   Create a new Location Permit.

   **Sample request**:

   .. sourcecode:: http

      POST /permit/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

      {
        "name": "A new Location Permit"
      }

   :<json string name: Name of the permit (required)

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Content-Type: application/json

      {
        "name": "A new Location Permit",
        "uuid": "00bd62a92a004faea233951510167cad"
      }



Update Location Permit
......................

.. http:put:: /permit/(permit_ref)

   Update a given Location Permit. Updates cannot be performed on archived permits.

   **Sample request**:

   .. sourcecode:: http

     PUT /permit/d6d22438096503fe72a7c161201c9373 HTTP/1.1
     Host: api.fieldaware.net
     Authorization: Token 687fe20baeef448bb30db579139dad33
     Accept: application/json

     {
       "name": "Updated Permit"
     }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT

  :statuscode 204: if the permit is successfully updated
  :statuscode 409: if the permit is archived
  :statuscode 422: if the payload provided is invalid


Archive Location Permit
.......................

.. http:put:: /permit/(permit_ref)/archive

   Archives a given Location Permit. By archiving a Location Permit it will be
   removed from any customers or locations using it.

   **Sample request**:

   .. sourcecode:: http

     PUT /permit/d6d22438096503fe72a7c161201c9373/archive HTTP/1.1
     Host: api.fieldaware.net
     Authorization: Token 687fe20baeef448bb30db579139dad33
     Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT

  :statuscode 204: if the permit is successfully archived
  :statuscode 409: if the permit is already archived


Unarchive Location Permit
.........................

.. http:put:: /permit/(permit_ref)/unarchive

   Unarchives a previously archived Location Permit.

   **Sample request**:

   .. sourcecode:: http

     PUT /permit/d6d22438096503fe72a7c161201c9373/unarchive HTTP/1.1
     Host: api.fieldaware.net
     Authorization: Token 687fe20baeef448bb30db579139dad33
     Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT

  :statuscode 204: if the permit is successfully unarchived
  :statuscode 409: if the permit is not archived


Delete Location Permit
......................

.. http:delete:: /permit/(permit_ref)

   Delete a given permit. Only archived Location Permits, and those non-archived
   that have not being linked to any users and/or locations can be deleted from
   the system.

   **Sample request**:

   .. sourcecode:: http

      DELETE /permit/00bd62a92a004faea233951510167cad HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

    HTTP/1.1 204 No Content

  :statuscode 204: if the permit is successfully updated
  :statuscode 409: if the permit is used on locations or users