> For the complete documentation index, see [llms.txt](https://docs.mastersoftgroup.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/objects/phone-objects.md).

# 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"
       }
    
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/objects/phone-objects.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
