Core - Addresses
================
.. Last update: 24/11/2021

The base url for the APIs in this page is at::

  /api/mobile/

A JSON file with OpenAPI data about all core-related admin APIs can be downloaded :download:`here </openapi/srv-core/api-src-WebMobile.json>`.

Get address list
----------------
Retrieves the :ref:`paged list<paged-list-api>` of addresses for th user

 .. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/addresses/list
     
Returns the list of all the documents of the specified end user::

  [
    {
      ID: 1234,                               // Int
      CreatedDate: "2021-01-01Z00:00:00T",    // Date
      LastUpated: "2021-01-01Z00:00:00T",     // Date
      LastUpdatedBy: "Administrator",         // String (nullable)
      DeletionDate: null,                     // Date (nullable)
      Type: 0,                                // Int
      Country: "ITA",                         // String
      County: "MI",                           // String
      City: "Milan",                          // String
      ZipCode: "20021",                       // String
      StreetAddress: "Piazza del Duomo",      // String
      Number: "1",                            // String
      ExtraData: "..."                        // String (nullable)
    },
    ...
  ]

The ``Type`` property value can be one of the :ref:`enum-addresstypes` enumeration.

The ``Country`` property value is a country code in the ISO3661 alpha-3 format.

Add or edit an address
----------------------
Allows the operator to add a new address on the user or edit an existing one

 .. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/addresses

The API accepts a request body in the following format::

  {
    ID: 1234,                             // Int
    Type: 0,                              // Int
    Country: "ITA",                       // String
    County: "MI",                         // String
    City: "Milan",                        // String
    ZipCode: "20021",                     // String
    StreetAddress: "Piazza del Duomo",    // String
    Number: "1",                          // String
    ExtraData: "..."                      // String (nullable)
  }
  
and might respond with one of the following errors:

``err_InvalidElement``
  One of the required data is not set, or the ``Country`` property is not a valid ISO3661 alpha-3 country code
  
``err_DuplicatedElement``
  The operator is trying to add a new residential/living address on a user that already has one
  
Delete an address
-----------------
Allows the user to mark an address as deleted

 .. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/addresses/{id}
     
| id: ID of the address to delete

The API might respond with one of the following errors:

``err_ElementDoesNotExist``
  No address has been found for the provided ID
  
``err_ElementAlreadyDeleted``
  The address related to the provided ID is already marked as deleted
  
``err_CannotDelete``
  The address relatedo to the provided ID is a primary residence address, and thus cannot be deleted
  
Get list of country codes
-------------------------
Gets a list of country codes available on the database:

 .. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/addresses/country-codes

Returns a positive Json response with list of the country codes and their localized name for issuing authorities::

  { 
    [
      {
        Code: "AUT",
        Label: "Austria"
      },
      { ... }
  }
  
The ``Code`` property value is a country code in the ISO3661 alpha-3 format.