Phone Numbers

See the List Phone Numbers API reference for the full endpoint specification.

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

await client.phoneNumbers.list();

client.phoneNumbers.list()

client.PhoneNumbers.List(context.TODO())

Most of the time you don’t. POST /v3/messages takes recipients with no from and picks the line itself — reusing the line the recipients’ existing chat is on, opening a new chat on the best available line, or moving them onto a fresh line when the current one can’t send. Adding lines to your account puts them in that rotation with no code change. See Sending Messages → Let Linq pick the line and Just hit send: introducing managed load balancing.

Where you do need a specific number is onboarding — showing a new user which line to text first, or giving them a contact card to save. That’s what GET /v3/available_number is for.

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

await client.availableNumber.retrieve();

client.availableNumber.retrieve()

client.AvailableNumber.Retrieve(context.TODO())

It returns the selected phone_number plus vcf_url: a time-limited vCard carrying that line’s contact card, with the selected number as the primary TEL and your other available lines as backups — so a recipient who saves it still has a path to you if the primary line goes down. The link expires, so call again for a fresh one.

• Pass to to make the choice sticky — recipients who already have a chat with you stay on the line they’re already on.
• Pass exclude_from to leave lines out of the pick, out of the sticky choice, and out of the vCard’s backup numbers. Entries must be E.164; excluding all of your available lines returns 400.
• With no to, you get the least-recently-used available line, always preferring a healthier reputation. Suggestions and your own sends both count as use, so successive calls cycle through the pool and new users spread evenly across it.

This does not reserve the line — pass the returned phone_number as from when you create the chat if you need that exact line.

Set a forwarding_number to route inbound calls on a line elsewhere. Pass an empty string (or null) to clear it. See the Update Phone Number API reference for the full endpoint specification.

curl -X PUT https://api.linqapp.com/api/partner/v3/phone_numbers/{phoneNumberId} \
  -H "Authorization: Bearer $LINQ_API_KEY"

await client.phoneNumbers.update({phoneNumberId});

client.phoneNumbers.update({phone_number_id})

client.PhoneNumbers.Update(context.TODO(), {phoneNumberId})

The API does not place or answer voice calls directly, but you can route calls around your Linq line:

• Inbound calls — Forward your Linq line to a number of your choice by setting a forwarding_number via the Update phone number endpoint above. Pass an empty string to clear the forwarding number.
• Outbound calls — If you own another number that supports caller-ID masking (for example, a Twilio number with Verified Caller ID), you can mask your Linq number over it so the Linq number displays on outbound calls.
• AI voice agents — Use a VOIP number (commonly Twilio) with the inbound/outbound setups above to route calls to and from your agent via the Twilio API.

See the FAQ for more.

Numbers are provisioned by your Linq representative — there is no self-serve create or delete endpoint on the V3 API. To add or release a line, contact support with the details of the line you want changed.

Numbers carry two independent fields you can react to:

• status — the line’s current sending state.
  • ACTIVE — sending and receiving normally.
  • FLAGGED — a service flag has degraded the number’s ability to send. New messages on a flagged line may fail with delivery errors.
• reputation — line-level prediction of where the line is heading based on the patterns in its conversations and its overall messaging activity. See the Phone Reputation guide for the HEALTHY / AT_RISK / CRITICAL values, what drives each one, and how to react.

The phone_number.status_updated webhook fires when either field changes, and every payload carries both pairs (previous_status / new_status and previous_reputation / new_reputation), so a single subscription covers both signals.

{
  "phone_number": "+12025551234",
  "previous_status": "ACTIVE",
  "new_status": "FLAGGED",
  "previous_reputation": "AT_RISK",
  "new_reputation": "CRITICAL",
  "changed_at": "2026-02-18T18:35:05.000Z"
}

You can also enable Flagged-number Slack notifications in the API Tooling settings to get a Slack message in your linked partner channel whenever a number’s status changes.

Recommended handling:

• Page on-call when a production line transitions to FLAGGED.
• Pause outbound sends on the affected line until it returns to ACTIVE.
• Contact your Linq representative for remediation.
• For reputation transitions to AT_RISK or CRITICAL, follow the playbook in the Phone Reputation guide — typically slow the line’s pace before the line ends up FLAGGED.

• Key Concepts: Phone Numbers
• Phone Reputation — line-level reputation scoring
• Sending Messages — sending without a from
• Webhooks: Phone number events
• API Reference: Phone Numbers
• API Reference: Get an available sending number