Get an available sending number

client.AvailableNumber.Get(ctx, query) (*AvailableNumberGetResponse, error)

GET/v3/available_number

Returns the best available line (E.164) to send from, applying smart number assignment. Optionally pass to recipients to make the choice “sticky” — reusing the line an existing chat with those recipients is already on. Without to, the best healthy line is chosen.

This is advisory: it does not reserve the line or change selection state. Pass the returned phone_number as from when you create the chat to guarantee the same line.

Also returns vcf_url: a time-limited link to a vCard (.vcf) for the chosen line, carrying its contact card (name/photo) with the chosen number as the primary TEL and the partner’s other healthy lines as backups. Share it with recipients so they can save the line as a contact.

ParametersExpand Collapse

query AvailableNumberGetParams

To param.Field[[]string]Optional

Recipient handles (E.164 or email) the message is destined for. When provided, an existing chat with these recipients makes the choice sticky. Repeat the parameter for multiple recipients.

ReturnsExpand Collapse

type AvailableNumberGetResponse struct{…}

The line smart number assignment selected, plus a shareable vCard.

PhoneNumber string

The selected sending line in E.164 format.

VcfURL string

Time-limited link to a vCard (.vcf) for the selected line. The card carries the line’s contact details with the selected number as the primary TEL and the partner’s other healthy lines as backups. The link expires; re-call this endpoint to mint a fresh one.

formaturi

Get an available sending number

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"),
  )
  availableNumber, err := client.AvailableNumber.Get(context.TODO(), linqgo.AvailableNumberGetParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", availableNumber.PhoneNumber)
}

{
  "phone_number": "+12025551234",
  "vcf_url": "https://s3.us-east-1.amazonaws.com/linq-attachments/vcf/9716d5c5/12025551234.vcf?X-Amz-Signature=..."
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "phone_number": "+12025551234",
  "vcf_url": "https://s3.us-east-1.amazonaws.com/linq-attachments/vcf/9716d5c5/12025551234.vcf?X-Amz-Signature=..."
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}