# Check phone connectivity

`GET /phone_ping`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/phone_ping`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/phone_ping`

Tests the connectivity of one or more supplied phone numbers. This connectivity check will return a
code indicating if the phone number is connected or disconnected.

## Sandbox environment

When simulating queries in the sandbox environment, the connectivity response will be determined by the phone number ending:

| Number Type | Response | Description |
|:------------|:---------|:------------|
| Any number ending in 9999 | | Simulate a timeout, will never return a result |
| Any number ending in 999 | C | Simulate a slow result, takes 20 seconds but returns as connected |
| Any number ending in 998 | D | Simulate a slow result, takes 20 seconds but returns as disconnected |
| Any number ending in 997 | U | Simulate a slow result, takes 20 seconds but returns as undetermined |
| Any number ending in 99 | I | Phone number Not Supported / Invalid | 
| Any number ending in 9 | D | Phone number is not connected |
| Any number ending in 8 | U | Phone number is undetermined |
| Any other number | C | Phone Number is connected |

## Request body

The details of the record to enhance

| Field | Type | Description |
|-------|------|-------------|
| `phones` | string | One or more (comma separated) 10 digit Australian phone number to be checked (0NSN format) Example: `0417034325` |
| `timeout` | integer [10..300] or null | Maximum number of seconds to wait for connectivity results before returning. If a result is not available within this time, the phone will be returned with a ping_result of `U` (Undetermined). Must be between 10 and 300 seconds. When supplied, this value is used exactly as given and overrides the default. If not specified, a default timeout is used that automatically scales with the number of phones submitted (30 seconds for fewer than 10 phones, increasing with larger batches). When checking many numbers it is recommended to either omit this parameter so the scaling default applies, or to supply a value large enough for all results to be returned. Example: `60` |

**Sample request**

```json
{
    "phones": "0417034325",
    "timeout": 60
}
```

## Responses

### 200 Result of phone ping check

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `api_reference` | string (uuid) | Example: `738d9a89-b6fe-4fc1-96be-1389b2a506a2` |
| `results` | array of objects | The checked phone numbers and their connectivity status |
| `results[].phone` | string | The checked phone number in 0NSN format Example: `0417034325` |
| `results[].ping_result` | string | The result of the connectivity check for the phone * `C` - The phone is connected * `D` - The phone is disconnected * `U` - The state of the phone number cannot be detected * `I` - The phone number is invalid Enum: `C`, `D`, `U`, `I` Example: `C` |
| `results[].info` | string | Additional information about the result Example: `Number Live` |
| `results[].carrier` | string | The carrier of the phone number (if available) Example: `Telstra` |
| `results[].geo_location` | string | Approximate geographic location for the phone number (if available) Example: `Sydney` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "738d9a89-b6fe-4fc1-96be-1389b2a506a2"
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))