# Phone Objects

| [Phone](#phone)                         | A Phone number for validation.                                  |
| --------------------------------------- | --------------------------------------------------------------- |
| [PhoneList](#phonelist)                 | Container for Phone numbers.                                    |
| [PhoneRestRequest](#phonerestrequest)   | Request wrapper for phone REST methods.                         |
| [PhoneRestResponse](#phonerestresponse) | Response wrapper for phone REST methods.                        |
| [ValidatedPhone](#validatedphone)       | A Phone number object containing the results of the validation. |

### Phone <a href="#phone" id="phone"></a>

The Phone structure is used to supply mobile phone numbers for validation.

#### fullPhone

Type: `String`. The mobile phone number with optional country code (e.g. '+61412345678').

#### country

Type: `String`. The two-character country code to be used for the validation (e.g. 'AU').

#### JSON Representation

```
    {
        "fullPhone": "+61412345678",
        "country": "AU"
    }
    
```

### PhoneList <a href="#phonelist" id="phonelist"></a>

An array or list of Phone structures.

#### JSON Representation

```
    [ 
        { 
            "fullPhone": "+61412345678",
            "country": "AU"
        },
        {
            "fullPhone": "+61487654321",
            "country": "AU"
        },
        ... 
    ]
    
```

### PhoneRestRequest <a href="#phonerestrequest" id="phonerestrequest"></a>

An PhoneRestRequest object is used when invoking the Harmony RightAddress phone validation REST service methods.

#### payload

Type: [PhoneList](#phonelist) The list of Phone structures being passed to the REST service method.

#### JSON Representation

```
    {
        "payload": 
            [
                { 
                    "fullPhone": "+61412345678",
   	                "country": "AU"
                },
                {
                    "fullPhone": "+61487654321",
                    "country": "AU"
                },
                ...
            ]
    }
    
```

### PhoneRestResponse <a href="#phonerestresponse" id="phonerestresponse"></a>

An PhoneRestResponse object is returned from the Harmony RightAddress phone validation REST service methods.

#### payload

Type: [PhoneList](#phonelist) The list of Phone structures being returned from the REST service method.

#### status

Type: `String`. The status of the request (i.e. 'SUCCESS' or 'ERROR').

#### messages

Type: `String[]`. Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]')

#### JSON Representation

```
    {
        "status": "SUCCESS",
        "messages": [],
        "payload": [
            {
                "fullPhone": "+61412345678",
                "country": "AU"
            }
        ]
    }
    
```

### ValidatedPhone <\<extends>> [Phone](#phone) <a href="#validatedphone" id="validatedphone"></a>

A ValidatedPhone object extends a standard Phone object and is returned in the validate method response.

See[ Phone](#phone) for inherited attributes.

#### countryCode

Type: `String`. Any country code associated with the supplied phone number (e.g. '+61').

#### areaCode

Type: `String`. Any area code associated with the supplied (non-mobile) phone number (e.g. '02').

#### localNumber

Type: `String`. The local part of the supplied number (e.g. '12345678')

#### operatorName

Type: `String`. The mobile operator associated with the supplied number (e.g. 'Vodafone Australia')

#### phoneStatus

Type: `String`. The current status of the mobile phone with the supplied number (e.g. 'connected|Network confirmed connection', 'disconnected|Network confirmed disconnection', 'indeterminate').

#### exception

Type: `String`. An exception message outlining the errors that occurred during validation for the phone numbers with 'indeterminate' phone status. (e.g. 'Number prefix missing', 'Network is forbidden', 'Invalid destination address.').

#### JSON Representation

```
    {
            "fullPhone": "+61412345678",
            "country": "AU",
            "countryCode": "61",
            "areaCode": "",
            "localNumber": "412345678",
            "operatorName": "Vodafone Australia",
            "phoneStatus": "connected|Network confirmed connection",
            "exception": ""
    },
    
    {
            "fullPhone": "61488888888",
            "country": "AU",
            "countryCode": "61",
            "areaCode": "",
            "localNumber": "488888888",
            "operatorName": "Unknown",
            "phoneStatus": "disconnected|Network confirmed disconnection",
            "exception": ""
     },
        
     {
            "fullPhone": "04123456789",
            "country": "AU",
            "countryCode": null,
            "areaCode": null,
            "localNumber": null,
            "operatorName": "",
            "phoneStatus": "indeterminate",
            "exception": "Number prefix missing"
      },
      
      {
            "fullPhone": "+64412345678",
            "country": "NZ",
            "countryCode": "64",
            "areaCode": "",
            "localNumber": "412345678",
            "operatorName": "",
            "phoneStatus": "indeterminate",
            "exception": "Invalid destination address."
       },
       
       {
            "fullPhone": "02 12345678",
            "country": "AU",
            "countryCode": "",
            "areaCode": "02",
            "localNumber": "12345678",
            "operatorName": "",
            "phoneStatus": "indeterminate",
            "exception": "Network is forbidden"
       }
    
```