Quickstart
Route your first inbound call from a Linq number to your voice platform in four steps.
This guide takes you from nothing to your first inbound call on your voice platform, with TLS-encrypted SIP signalling to your endpoint.
Before you begin
Section titled “Before you begin”- An API key, exported as
LINQ_API_KEY. See Authentication. - A Linq phone number on your account.
GET /v3/phone_numberslists your numbers. - The Pro or Enterprise plan. Your Linq representative can help with pricing.
- A voice platform or SIP server that accepts inbound SIP.
Set up your first call
Section titled “Set up your first call”-
Get your platform’s SIP address
Linq sends your calls to your platform’s SIP address. Find it in your platform’s inbound SIP settings. Use one of its TLS forms: a
sips:URI, or asip:URI with;transport=tls, kept as your platform lists it (for examplesip:sip.example.com:5061;transport=tls). Always include the port, using the TLS port your platform lists; Linq assumes 5060 when the URI has none. Don’t include a user part (the part before@); Linq sets it to the called number on each call.Use the host and port only, for example
sips:sip.example.com:5061. Add your Linq number, including the+, where your platform takes a number you bring yourself, and point it at your agent. Linq sendsINVITE sips:[email protected]:5061. If your platform routes on its own ID, such as a project or account ID, route on the called number in the Request-URI user part instead.Fill in the rest of your platform’s inbound settings from What to enter in your platform. Some platforms also need your app to accept the call on their side, so check your platform’s inbound-call steps.
-
Create a SIP profile
A SIP profile tells Linq where to send calls. Create one with
POST /v3/sip-profiles, using the URI from step 1, with no user part:Terminal window curl -X POST https://api.linqapp.com/api/partner/v3/sip-profiles \-H "Authorization: Bearer $LINQ_API_KEY" \-H "Content-Type: application/json" \-d '{"name": "my-voice-agent","primary_uri": "sips:sip.example.com:5061"}'You should see a
201response. Itsidstarts withsip_. Export it for step 3 withexport SIP_PROFILE_ID=<your id>:{"id": "sip_8a3f9c2b1d4e4f5a9b8c7d6e5f4a3b2c","name": "my-voice-agent","primary_uri": "sips:sip.example.com:5061","backup_uri": null,"version": 1,"assigned_number_count": 0,"created_at": "2026-10-29T10:30:00Z","updated_at": "2026-10-29T10:30:00Z"}If you get
2015, a profile with this URI already exists. List your profiles withGET /v3/sip-profilesand reuse itsid. -
Assign it to your number
Send the profile’s
idtoPUT /v3/phone-numbers/{phoneNumber}/sip-profile, with your number in the path in E.164:Terminal window curl -X PUT https://api.linqapp.com/api/partner/v3/phone-numbers/+14155550100/sip-profile \-H "Authorization: Bearer $LINQ_API_KEY" \-H "Content-Type: application/json" \-d "{\"sip_profile_id\": \"$SIP_PROFILE_ID\"}"You should see a
200response with yourphone_numberand asip_profile_idequal to your profile’sid. Keep a record of which profile each number has: the API doesn’t return a number’s profile, andGET /v3/sip-profiles/{sipProfileId}shows only how many numbers use a profile (assigned_number_count). Don’t send the assign request again just to check it: it replaces the number’s current profile with the one you send.Call forwarding: assigning a SIP profile takes precedence over the number’s call forwarding (its
forwarding_number), without clearing it.Allow about 5 minutes after you assign, move or clear a number’s profile before test calls reach the new endpoint. Calls in progress keep going where they started.
Error What it means 2033The number isn’t published, or can’t be set up for voice. 2006The number isn’t yours, or your API key is from another environment. 2019The number or the profile wasn’t found.
Before you call
Section titled “Before you call”- The assign request in step 3 returned
200with your profile’sid. - Your firewall allows Linq’s addresses.
- Your platform’s certificate is valid for the host in your URI.
- Your platform is ready: your Linq number is added if it routes on the called number, and your app accepts the call if your platform needs that.
Optionally, subscribe to call events first, so a failed call leaves an event as well as a status.
-
Call your number
Call your Linq number from a mobile phone. You should see your agent answer. Your platform receives the INVITE from step 1, with the caller in the
Fromheader.To find the call afterwards, list your number’s calls and fetch one by its
id; see Find a call.
If nothing arrives
Section titled “If nothing arrives”- You assigned the number less than 5 minutes ago: allow about 5 minutes for the assignment to apply, then call again.
- Check the call’s
status: see Find a call, then look it up in Call outcomes. - Your platform saw no INVITE: check that the
200from step 3 showed your profile’sid, and thatassigned_number_countinGET /v3/sip-profiles/{sipProfileId}went up. Then check that your firewall allows Linq’s addresses. - Your platform logged a
404: it doesn’t know the called number. Add the number, including the+.
Next steps
Section titled “Next steps”- How calls work for your agent: what Linq decides on a call, what you decide, and the logic to build around calls.
- Connect your SIP endpoint: call webhooks, a backup endpoint, codecs, custom SIP headers and every setting.
- Outbound calling (early access): place calls from your Linq numbers through Linq.
- SIP Profiles API reference