Phone Numbers

Get an available sending 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.

Pass type to pick only from one kind of line — for example RCS to get one of your Android (RCS-only) lines. Omit it to choose from all of them.

get/v3/available_number

Request

  • Base URL: https://api.linqapp.com/api/partner
  • URL: https://api.linqapp.com/api/partner/v3/available_number
  • Auth: HTTP bearer

Query parameters

tostring[]

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.

exclude_fromstring[]

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.

type'RCS' | 'iMessage'

Only return a line of this kind. Case-insensitive.

  • RCS: Android lines, which send RCS (and SMS) only.
  • iMessage: iMessage lines.

Applies to the returned phone_number, to the sticky choice when to is given (an existing chat on another kind of line is not returned), and to the vCard's backup numbers. Omit it to choose from all your lines. Returns 503 if you have no available line of this kind.

Response

Available number resolved successfully

phone_numberstring required

The selected sending line in E.164 format.

vcf_urlstring uri required

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.

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.