# Phone Numbers

## List phone numbers

`client.PhoneNumbers.List(ctx) (*PhoneNumberListResponse, error)`

**get** `/v3/phone_numbers`

Returns all phone numbers assigned to the authenticated partner.
Use this endpoint to discover which phone numbers are available for
use as the `from` field when creating a chat, listing chats, or sending a voice memo.

### Returns

- `type PhoneNumberListResponse struct{…}`

  - `PhoneNumbers []PhoneNumberListResponsePhoneNumber`

    List of phone numbers assigned to the partner

    - `ID string`

      Unique identifier for the phone number

    - `HealthStatus PhoneNumberListResponsePhoneNumberHealthStatus`

      **[BETA]** Current health for a phone line. Always present — lines start at `HEALTHY` and may shift based on aggregate engagement and delivery signals across all conversations on the line.

      Unlike chat health, line health does not include `opted_out` — opt-out applies to individual recipients, not the whole line.

      See the [Phone Health guide](/guides/phone-numbers/phone-health) for what each status means and how to react.

      - `DocURL string`

        Deep-link to the relevant section of the Phone Health guide for this status.

      - `Status string`

        Current health of this phone line as assessed by risk-service.

        - `HEALTHY` — No elevated risk detected.
        - `AT_RISK` — Elevated risk indicators present; consider reducing send volume or reviewing messaging patterns.
        - `CRITICAL` — High risk; further sending may result in line flagging or restriction.

        Defaults to `HEALTHY` for lines that have not yet been scored.

        - `const PhoneNumberListResponsePhoneNumberHealthStatusStatusHealthy PhoneNumberListResponsePhoneNumberHealthStatusStatus = "HEALTHY"`

        - `const PhoneNumberListResponsePhoneNumberHealthStatusStatusAtRisk PhoneNumberListResponsePhoneNumberHealthStatusStatus = "AT_RISK"`

        - `const PhoneNumberListResponsePhoneNumberHealthStatusStatusCritical PhoneNumberListResponsePhoneNumberHealthStatusStatus = "CRITICAL"`

    - `PhoneNumber string`

      Phone number in E.164 format

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  phoneNumbers, err := client.PhoneNumbers.List(context.TODO())
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", phoneNumbers.PhoneNumbers)
}
```

#### Response

```json
{
  "phone_numbers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+12025551234",
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/guides/phone-numbers/phone-health#healthy"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "phone_number": "+12025559876",
      "health_status": {
        "status": "AT_RISK",
        "doc_url": "https://docs.linqapp.com/guides/phone-numbers/phone-health#at-risk"
      }
    }
  ]
}
```