Get an available sending number

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.

Query ParametersExpand Collapse

to: optional array of string

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

phone_number: string

The selected sending line in E.164 format.

vcf_url: 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

curl https://api.linqapp.com/api/partner/v3/available_number \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY"

{
  "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
}