Customers
---------

This API allows listing, retrieving, creating, updating,
and deleting customers, as well as the contacts and locations of a
given customer. They are identified by UUID.

.. (comment out reference to external IDs for now)
   They can also be identified by their external ID, if they have one.
   Currently this is specified by passing the query parameter ``by=externalID``
   to all API methods with ``(customer_ref)`` in their URL.


List Customers
..............

.. http:get:: /customer/

   List all customers.

   **Sample request**:

   .. sourcecode:: http

      GET /customer/?pageSize=3&page=2 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json
      Link: <https://api.fieldaware.net/customer/?page=0&pageSize=3>; rel=first,
            <https://api.fieldaware.net/customer/?page=62&pageSize=3>; rel=last,
            <https://api.fieldaware.net/customer/?page=1&pageSize=3>; rel=prev,
            <https://api.fieldaware.net/customer/?page=3&pageSize=3>; rel=next

      {
        "count": 187,
        "items": [
          {
            "link": {
              "url": "https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f",
              "rel": "detail"
            },
            "uuid": "929022257f1c440089cebcbd510e2d2f",
            "name": "Murphy's Bar and Grill",
            "customerId": 3
          },
          {
            "link": {
              "url": "https://api.fieldaware.net/customer/8b9b9f255d5d4e2d9e94bde9d6e3ed90",
              "rel": "detail"
            },
            "uuid": "8b9b9f255d5d4e2d9e94bde9d6e3ed90",
            "name": "Dallas Museum of Art",
            "customerId": 4
          },
          {
            "link": {
              "url": "https://api.fieldaware.net/customer/1671818094bd465d92f1268323763513",
              "rel": "detail"
            },
            "uuid": "1671818094bd465d92f1268323763513",
            "name": "Duck Commander",
            "customerId": 5
        ],
        "page": 2,
        "sortedBy": [],
        "pageSize": 3
      }

   :query sortedBy:  Available sorting criteria: ``customerId``, ``name``
   :query taxable: Boolean denoting filtering by taxable customer
   :query name: A filtering value for customer name
   :query glAccount: A filtering value for glAccount
   :query email: A filtering value for customer email address
   :>json int number: Total number of customers
   :>json array items: A list of JSON objects representing customers
   :>json int page: Page number
   :>json array sortedBy: A list of ordered by (strings), can be ``name`` and ``customerId``
   :>json int pageSize: NUmber of JSON objects (representing customers) by page.


Get Customer
............

.. http:get:: /customer/(customer_ref)

   Retrieve a given customer.

  **Sample request**

  .. sourcecode:: http

     GET /customer/929022257f1c440089cebcbd510e2d2f HTTP/1.1
     Host: api.fieldaware.net
     Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
     Accept: application/json

  **Sample response**:

  .. sourcecode:: http

     HTTP/1.1 200 OK
     Content-Type: application/json
     Link: <https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f>; rel=self

     {
       "website": "www.fieldaware.com",
       "account": "1988",
       "glAccount": null,
       "name": "Murphy's Bar and Grill",
       "discount": null,
       "notes": "See Bartender",
       "fax": null,
       "customerId": 3,
       "phone": "972-704-1800",
       "billingLocation": {
         "isBilling": true,
         "customer": {
           "uuid": "929022257f1c440089cebcbd510e2d2f"
         },
         "name": "McKinney",
         "locality": "McKinney",
         "country": "United States",
         "region": "TX",
         "tax": {
             "name": "default tax",
             "group": "Taxes"
         },
         "postcode": "75070",
         "lat": null,
         "lng": null,
         "type": null,
         "customFields": {},
         "streetName": "1909 Clinton Dr",
         "uuid": "151a29821d594eabb060160360cd26cf"
       },
       "taxable": false,
       "onHold": false,
       "customFields": {},
       "email": "Andy.murphy@fieldaware.com",
       "uuid": "929022257f1c440089cebcbd510e2d2f"
     }

  :>json string website: Customer website
  :>json string account: Customer account
  :>json string glAccount: Null or string
  :>json string name: Customer name
  :>json number discount: Discount
  :>json string notes: Customer notes
  :>json string fax: Fax number
  :>json int customerId: Customer id number
  :>json string phone: Customer phone number
  :>json obj billingLocation: JSON object
  :>json bool taxable:
  :>json bool onHold:
  :>json obj customFields: JSON obj representing custom fields
  :>json string email: Customer email
  :>json string uuid: Customer unique reference number


Create Customer
...............

.. http:post:: /customer/

   Create a new minimal customer.

   **Sample request:**

   .. sourcecode:: http

      POST /customer/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Content-Type: application/json
      Accept: application/json

      {
        "name": "ABC solicitors",
        "location": {
          "streetName": "1909 Clinton Dr",
          "locality": "McKinney"
        }
      }

   :<json string name: Name of the customer (required)
   :<json obj location:  Location object, see `Create Location`_ (required)

   **Sample request:**

   .. sourcecode:: http

      POST /customer/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Content-Type: application/json
      Accept: application/json

      {
        "name": "ABC solicitors",
        "email": "office.manager@abcsolicitors.com",
        "phone": "1234567890",
        "fax": "1234567891",
        "notes":  "",
        "website": "www.abcsolicitors.com",
        "account": "1234",
        "glAccount": "5678",
        "discount": 10,
        "taxable": true,
        "onHold": false,
        "location": {
          "name": "McKinney",
          "streetName": "1909 Clinton Dr",
          "locality": "McKinney",
          "lat": 33.1871,
          "lng": -96.7453,
          "region":  "TX",
          "postcode": "75070",
          "country":  "United States",
          "isBilling": true,
          "type": "headquarters",
          "tax": {
            "name": "default tax",
            "group": "Taxes"
          },
          "customFields": {
            "access": "easy access"
          }
        },
        "customFields": {
          "fleet": "standard"
        }
      }

   :<json string name: Name of the customer (required)
   :<json string email: Email address of the customer
   :<json string phone: Phone number of the customer
   :<json string fax: Fax number of the customer
   :<json string notes:  Notes about the customer
   :<json string website: Website URL of the customer
   :<json string account: Account of the customer
   :<json string glAccount: General Ledger account of the customer
   :<json number discount: The discount rate for the customer, e.g. ``10`` for a 10% discount
   :<json boolean taxable: Whether this customer is taxable; defaults to ``true``
   :<json string onHold: Whether this customer is on hold; defaults to ``false``
   :<json obj location:  Location object, see `Create Location`_ (required)
   :<json string location.name: A descriptive name of the location (required)
   :<json string location.streetName: Street name and number of the location (required)
   :<json string location.locality: City, town or municipality of the location (required)
   :<json number location.lat: latitude value (required)
   :<json number location.lng: longitude value (required)
   :<json string location.region:  Greater region of the location, e.g. state
   :<json string location.postcode: Post/zip code of the location
   :<json string location.country:  Country of the location
   :<json boolean location.isBilling: Whether this is a billing location; defaults to ``false``
   :<json string location.type: Type of the location; can be ``"headquarters"``, ``"branch"``, ``"residential"`` or ``"billing"``
   :<json string location.taxName: Name of the tax. Required if taxGroup has a value
   :<json string location.taxGroup: Group of the tax. Required if taxName has a value
   :<json obj location.customFields: location custom fields, see :ref:`Custom Fields <custom-fields>`
   :<json obj customFields: customer custom fields, see :ref:`Custom Fields <custom-fields>`


   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/customer/abc52b3be17242ebad5a81d84c6eab7c

      {
        "link": {
          "url": "https://api.fieldaware.net/customer/4d18011294364a85a1c5541b9b4a0eee",
          "rel": "detail"
        },
        "location": {
          "link": {
            "url": "https://api.fieldaware.net/location/3b0fd4f427ac47bfa02c956a8f3179c9",
            "rel": "detail"
          },
          "uuid": "4a1de64d6b184abfb5692d2443dfa4d2",
        },
        "uuid": "3b0fd4f427ac47bfa02c956a8f3179c9",
        "email": "user10@glidebooks.com",
        "firstName": "Blaise",
        "lastName": "Champlin",
        "locale": "en_US",
        "phone": null,
        "platform": "ios",
        "role": "Admin",
        "timezone": "Europe/Dublin",
        "customFields": {},
      }

   :>json obj link: JSON object with a link to the created customer
   :>json string uuid: UUID ref number of the created customer
   :>json obj location: JSON object representing customer's location


Update Customer
...............

.. http:put:: /customer/(customer_ref)

   Update a given customer.

   **Sample request**:

   Same as `Create Customer`_ excluded **location**.

   In addition, to change the billing location, the following request can be issued

   .. sourcecode:: http

      PUT /customer/e14a3c9949ea4cbd98d73fa8046c7577 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Content-Type: application/json
      Accept: application/json

      {
        "billingLocation": {
          "uuid": "e14a3c9949ea4cbd98d73fa8046c7577"
        }
      }

   :<json string billingLocation.uuid: The uuid of a already existing customer location


Delete Customer
...............

.. http:delete:: /customer/(customer_ref)

   Delete a given customer.

   **Sample request**:

   .. sourcecode:: http

      DELETE /customer/1b9bbb54090e40c3a78f6111428776c5 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

   **Sample response**

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Contacts
--------

A customer can have zero or more contacts. Contacts are identified by UUID.


List Contacts
.............

.. http:get:: /customer/(customer_ref)/contact/

       List all contacts for the given customer.

.. http:get:: /contact/

       List all contacts.

   **Sample request:**

   .. sourcecode:: http

      GET /customer/929022257f1c440089cebcbd510e2d2f/contact/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample response**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json
      Link: <https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f/contact/?page=0>; rel=first,
            <https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f/contact/?page=0>; rel=last

      {
        "count": 1,
        "items": [
          {
            "customer": {
              "link": {
                "url": "https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f",
                "rel": "detail"
              },
              "uuid": "929022257f1c440089cebcbd510e2d2f"
            },
            "uuid": "cac42fd815114d79831f87e94c0c53df",
            "firstName": "Andy",
            "lastName": "Murphy",
            "phone": "972-704-1800",
            "link": {
              "url": "https://api.fieldaware.net/contact/cac42fd815114d79831f87e94c0c53df",
              "rel": "detail"
            },
            "email": "FieldAwareTraining@fieldaware.com"
          }
        ],
        "page": 0,
        "sortedBy": [],
        "pageSize": 20
      }

   :query sortedBy:  Available sorting criteria: ``firstName``, ``lastName``, ``email``, ``phone``, ``customer``
   :query firstName: a filtering value for firstName
   :query lastName: a filtering value for lastName
   :query email: a filtering value for email
   :query phone: a filtering value for phone
   :query customer: a filtering value for customer uuid (if not specified in the url)


Get Contact
...........

.. http:get:: /customer/(customer_ref)/contact/(contact_ref)
.. http:get:: /contact/(contact_ref)

   Retrieve a given contact.

   **Sample request**

   .. sourcecode:: http

      GET /customer/929022257f1c440089cebcbd510e2d2f/contact/cac42fd815114d79831f87e94c0c53df HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json
      Link: <https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f>; rel=customer,
            <https://api.fieldaware.net/contact/cac42fd815114d79831f87e94c0c53df>; rel=self

      {
        "customer": {
          "uuid": "929022257f1c440089cebcbd510e2d2f"
        },
        "phone": "972-704-1800",
        "uuid": "cac42fd815114d79831f87e94c0c53df",
        "firstName": "Andy",
        "lastName": "Murphy",
        "customFields": {},
        "email": "FieldAwareTraining@fieldaware.com"
      }


Create Contact
..............

.. http:post:: /customer/(customer_ref)/contact/
.. http:post:: /contact/

   Create a new minimal contact for the given customer.

   **Sample request**

   .. sourcecode:: http

      POST /customer/8e78aa909ec941c2b5cccff7be967311/contact/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json
      Content-Type: application/json

      {
        "firstName": "John"
      }

   or

   **Sample request**

   .. sourcecode:: http

      POST /contact/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json
      Content-Type: application/json

      {
        "firstName": "John",
        "customer": {
          "uuid": "8e78aa909ec941c2b5cccff7be967311"
        }
      }

   **Sample request**

   .. sourcecode:: http

      POST /contact/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Content-Type: application/json
      Accept: application/json

      {
        "firstName": "John",
        "lastName": "Smith",
        "email": "john.smith@abcsolicitors.com",
        "phone": "012-345-678-901",
        "customFields": {
          "9fa34e4b724f4ef7894b0d2cb5de1a06": "Doctor"
        },
        "customer": {
          "uuid": "929022257f1c440089cebcbd510e2d2f"
        }
      }

   :<json string firstName: First name of the contact (required)
   :<json string lastName: Last name of the contact
   :<json string email: Email address of the contact
   :<json string phone: Phone number of the contact
   :<json object customFields: see :ref:`Custom Fields <custom-fields>`
   :<json object customer: required if not part of URL
   :<json string customer.uuid: customer uuid


   **Sample Response**

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/contact/9885528de57d48bb82e384270c29669b

      {
        "link": {
          "url": "https://api.fieldaware.net/contact/9885528de57d48bb82e384270c29669b",
          "rel": "detail"
        },
        "customer": {
          "uuid": "929022257f1c440089cebcbd510e2d2f"
        },
        "phone": "012-345-678-901",
        "uuid": "cac42fd815114d79831f87e94c0c53df",
        "firstName": "John",
        "lastName": "Smith",
        "customFields": {},
        "email": "john.smith@abcsolicitors.com"
      }

   :>json obj link: JSON obj
   :>json string uuid: UUID reference number of the created customer


Update Contact
..............

.. http:put:: /customer/(customer_ref)/contact/(contact_ref)
.. http:put:: /contact/(contact_ref)

   Update a given contact of a given customer.

   **JSON request body**

   Same as `Create Contact`_, without ``customer`` and and with all other properties
   being optional.

   .. note::
      It is not possible to change the customer of a contact.

   **Sample request**:

   .. sourcecode:: http

      PUT /customer/8e78aa909ec941c2b5cccff7be967311/contact/32c6a0b8b4624d6ba9265b1bf2033953 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

      {
        "firstName": "Andrew"
      }

   **Sample request**:

   .. sourcecode:: http

      PUT /contact/32c6a0b8b4624d6ba9265b1bf2033953 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

      {
        "firstName": "Andrew"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Delete Contact
..............

.. http:delete:: /customer/(customer_ref)/contact/(contact_ref)
.. http:delete:: /contact/(contact_ref)

   Delete a given contact.

   **Sample request**:

   .. sourcecode:: http

      DELETE /contact/32c6a0b8b4624d6ba9265b1bf2033953 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

   **Sample request**:

   .. sourcecode:: http

      DELETE /customer/8e78aa909ec941c2b5cccff7be967311/contact/32c6a0b8b4624d6ba9265b1bf2033953 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Locations
---------

A customer can have zero or more locations. Locations are identified by UUID.


List Locations
..............

.. http:get:: /customer/(customer_ref)/location/

   List all locations for the given customer.

.. http:get:: /location/

   List all locations.

   **Sample request**

   .. sourcecode:: http

      GET /location/?pageSize=2 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json


   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json
      Link: <https://api.fieldaware.net/location/?page=0&pageSize=2>; rel=first,
            <https://api.fieldaware.net/location/?page=132&pageSize=2>; rel=last,
            <https://api.fieldaware.net/location/?page=1&pageSize=2>; rel=next

      {
        "count": 264,
        "items": [
          {
            "link": {
              "url": "https://api.fieldaware.net/location/067e238dd9354ea09073babbcbefa053",
              "rel": "detail"
            },
            "name": "Valley View",
            "customer": {
              "link": {
                "url": "https://api.fieldaware.net/customer/929022257f1c440089cebcbd510e2d2f",
                "rel": "detail"
              },
              "uuid": "929022257f1c440089cebcbd510e2d2f"
            },
            "uuid": "067e238dd9354ea09073babbcbefa053",
            "locality": "Valley View",
          },
          {
            "link": {
              "url": "https://api.fieldaware.net/location/08c46e0d609b406b9e9f04f25fc261ee",
              "rel": "detail"
            },
            "name": "US Headquarters",
            "customer": {
              "link": {
                "url": "https://api.fieldaware.net/customer/06d4fc8985e54574b9f96e6105d998c3",
                "rel": "detail"
              },
              "uuid": "06d4fc8985e54574b9f96e6105d998c3"
            },
            "uuid": "08c46e0d609b406b9e9f04f25fc261ee",
            "locality": "Addison",
          }
        ],
        "page": 0,
        "sortedBy": [],
        "pageSize": 2
      }

   :query sortedBy: Available sorting criteria: ``name``, ``streetName``, ``locality``, ``region``, ``postcode``, ``country``, ``isBilling``, ``type``
   :query name: a name value to filter for
   :query streetName: a street name value to filter for
   :query locality: a locality value to filter for
   :query region: a region value to filter for
   :query postcode: a postcode value to filter for
   :query country: a country value to filter for
   :query isBilling: a billing value to filter for
   :query type: a type value to filter for
   :query customer: a value for the customer uuid (if not in specified in the url)


Get Location
............

.. http:get:: /customer/(customer_ref)/location/(location_ref)
.. http:get:: /location/(location_ref)

    Retrieve a given location.

   **Sample request**:

   .. sourcecode:: http

      GET /location/08c46e0d609b406b9e9f04f25fc261ee HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json
      Link: <https://api.fieldaware.net/customer/06d4fc8985e54574b9f96e6105d998c3>; rel=customer,
      <https://api.fieldaware.net/location/08c46e0d609b406b9e9f04f25fc261ee>; rel=self

   **Sample response**:

   .. sourcecode:: http

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

      {
        "isBilling": false,
        "customer": {
          "uuid": "06d4fc8985e54574b9f96e6105d998c3"
        },
        "tax": {
          "group": "Taxes",
          "name": "default tax"
        },
        "name": "US Headquarters",
        "locality": "Addison",
        "country": null,
        "region": "TX",
        "postcode": "75001",
        "lat": null,
        "lng": null,
        "type": null,
        "customFields": {},
        "streetName": "15280 Addison Rd",
        "uuid": "08c46e0d609b406b9e9f04f25fc261ee"
      }

Latitude and longitude (**lat**, **lng**) field will always be ``null`` unless the values has been explicitly set (via WebApp, device or API).


Create Location
...............

.. http:post:: /customer/(customer_ref)/location/

   Create a new minimal location for the given customer.

   **Sample request**:

   .. sourcecode:: http

      POST /customer/beb65ace45ae487eb78b48729a502612/location/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Content-Type: application/json
      Accept: application/json

      {
        "name": "Positional location",
        "lat": 12.98,
        "lng": 10.34
      }


   **Sample request**:

   .. sourcecode:: http

      POST /customer/beb65ace45ae487eb78b48729a502612/location/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Content-Type: application/json
      Accept: application/json

      {
        "streetName": "23 Cloud Avenue",
        "locality": "Donegal"
      }


   **Sample request**:

   .. sourcecode:: http

      POST /customer/beb65ace45ae487eb78b48729a502612/location/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Content-Type: application/json
      Accept: application/json

      {
        "name": "Narrow st House",
        "lat": 12.09,
        "lng": 34.90,
        "streetName": "10 Narrow Street",
        "locality": "Dublin",
        "region":  "County Dublin",
        "postcode": "Dublin9",
        "country":  "Ireland",
        "isBilling": false,
        "type": "branch",
        "tax": {
          "name": "TaxName1",
          "group": "TaxGroup1"
        },
        "customFields": {
            "abc65ace99ae487eb78b48729a503333": true
        }
      }

   :<json string name: A descriptive name of the location (required, alternative 1)
   :<json number lat: Latitude value (required, alternative 1)
   :<json number lng: Longitude value (required, alternative 1)
   :<json string streetName: Street name and number of the location (required, alternative 2)
   :<json string locality: City, town or municipality of the location (required, alternative 2)
   :<json string region: Region name, for example State
   :<json string postcode: Post/zip code of the location
   :<json string country: Country of the location
   :<json bool isBilling: Whether this is a billing location; defaults to false.
   :<json string type: Type of the location: one of ``headquarters``, ``branch``, ``residential`` or ``billing`` (nullable)
   :<json obj tax: JSON obj representing tax
   :<json string tax.name: Name of the tax. Required if tax field is present.
   :<json string tax.group: Group of the tax. Required if tax field is present.
   :<json obj customFields: JSON objects, mapping of declaration keys to values

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 CREATED
      Content-Length: 153
      Content-Type: application/json
      Location: https://api.fieldaware.net/location/b2754175ac5a4c31b3d41b062819c02c

      {
        "link": {
          "url": "https://api.fieldaware.net/location/b2754175ac5a4c31b3d41b062819c02c",
          "rel": "detail"
        },
        "uuid": "08c46e0d609b406b9e9f04f25fc261ee"
        "isBilling": false,
        "customer": {
          "uuid": "06d4fc8985e54574b9f96e6105d998c3"
        },
        "tax": {
          "group": "TaxName1",
          "name": "TaxGroup1"
        },
        "name": "Narrow st House",
        "locality": "Dublin",
        "country": "Ireland",
        "region": "County Dublin",
        "postcode": "Dublin9",
        "lat": 12.09,
        "lng": 34.90,
        "type": "branch",
        "customFields": {
            "abc65ace99ae487eb78b48729a503333": true
        },
        "streetName": "10 Narrow Street",
      }

   :>json obj link: JSON object
   :>json string uuid: UUID ref number of the created location


   .. note::
      At least a full set (alternative 1 or 2) of required fields must be provided.


.. http:post:: /location/

   Create a new minimal location.

   **Sample request**:

   .. sourcecode:: http

      POST /location/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Content-Type: application/json
      Accept: application/json

      {
        "streetName": "11 Rain Avenue",
        "locality": "Dublin",
        "customer" : {
          "uuid": "beb65ace45ae487eb78b48729a502612"
        }
      }

   **Sample request**:

   .. sourcecode:: http

      POST /location/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Content-Type: application/json
      Accept: application/json

      {
        "name": "Narrow st House",
        "streetName": "10 Narrow Street",
        "locality": "Dublin",
        "lat": 12.98,
        "lng": 10.34
        "region":  "County Dublin",
        "postcode": "Dublin9",
        "country":  "Ireland",
        "isBilling": false,
        "type": "branch",
        "tax": {
          "name": "TaxName2",
          "group": "TaxGroup1"
        },
        "customFields": {
            "uyt65ace45ae487eb78b48729a501111" : "Is available?"
        },
        "customer" : {
          "uuid": "beb65ace45ae487eb78b48729a502612"
        }
      }


   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/location/abed1b946a5b470c8a8bf78b92abc6a6

      {
        "link": {
          "url": "https://api.fieldaware.net/location/abed1b946a5b470c8a8bf78b92abc6a6",
          "rel": "detail"
        },
        "uuid": "abed1b946a5b470c8a8bf78b92abc6a6"
      }

   :>json obj link: JSON object
   :>json string uuid: UUID ref number of the created location


Update Location
...............

.. http:put:: /customer/(customer_ref)/location/(location_ref)
.. http:put:: /location/(location_ref)

   Update a given location of a given customer.

   **JSON request body**:

   Same as `Create Location`_, without **customer** and
   and with all other properties being optional.

   .. note::

     It is not possible to change the customer of a location.

   **Sample request**:

   .. sourcecode:: http

      PUT /location/01c2a06da8364f8face0c4993dff89b6 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

      {
        "name": "new Location"
      }

   :<json string name: New name of the location

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Even if the webapp and/or a device display map value for latitude and longitude (``lat``, ``lng``) any attempt to
remove it (passing the ``null`` value) won't succeed unless the value has been explicitly set (namely when is present
in the GET response).


Delete Location
...............

.. http:delete:: /customer/(customer_ref)/location/(location_ref)
.. http:delete:: /location/(location_ref)

   Delete a given location of a given customer.

   If the given location is the only location of the customer, the response
   will be a 409 Conflict Error.

   **Sample request**:

   .. sourcecode:: http

      DELETE /location/01c2a06da8364f8face0c4993dff89b6 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT

.. _associate-permit-to-location:

Associate Location Permit to a Location
.......................................

.. warning:: The following feature is only available if the Location Permit feature is enabled.

.. http:put:: /location/(location_ref)

   Location permits can be associated with locations. This can be done
   by passing a list of uuids identifying location permits in a PUT request
   to the ``/location`` endpoint.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "permits": [
           {"uuid": "00bd62a92a004faea233951510167cad"},
           {"uuid": "bd62a0092a0041510167cadfaea23395"}
        ]
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Content-Type: application/json

  :statuscode 204: if the update is successful
  :statuscode 409: if any of the permits used is not found, or is archived
  :statuscode 422: if the payload provided is invalid