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 available line is chosen, always preferring lines with a healthier reputation.

This does not reserve the line. Without to, the least-recently-used available line is returned — suggestions and your own sends (including an explicit from on chat creation) both count as use, so successive calls cycle through your available lines and traffic spreads evenly. 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 available lines as backups. Share it with recipients so they can save the line as a contact. Lines you pass in exclude_from are left out of the vCard too.

Query ParametersExpand Collapse

exclude_from: optional array of string

Lines (E.164) to leave out of this selection. Applies to the returned phone_number, to the sticky choice when to is given, and to the vCard’s backup numbers. Repeat the parameter for multiple lines; use %2B for the leading +.

Numbers that are not your lines are ignored. Every entry must be E.164 — a value like 4155551234 is rejected rather than silently skipped. Excluding every one of your available lines returns 400.

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 available 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
}