Skip to content
Linq

Connect your SIP endpoint

Every setting for your SIP endpoint and your SIP profile, plus codecs, custom SIP headers, failover, call events and common issues.

This page lists every setting you need to connect a SIP endpoint to your Linq numbers: what to set on your endpoint, what to set at Linq, codecs, custom SIP headers, failover, call events and how to fix common problems. It works for any SIP server or voice-agent platform. For a first call, start with the Quickstart.

What Linq does and doesn't do on a call

Linq does:

  • relay the SIP signalling, and stay in that path for the whole call
  • send calls over TLS to a sips: URI or a sip:…;transport=tls URI; TLS covers the signalling, and the audio uses RTP or SRTP as negotiated in SDP
  • add the custom SIP headers you set on your profile to every INVITE
  • place the calls your platform sends from your Linq numbers, with outbound calling (early access)

Linq doesn’t:

  • carry the audio: it flows directly between the phone network and your endpoint
  • change the SDP, so the codec is negotiated end to end
  • send credentials to your endpoint
  • set custom SIP headers per call
  • put the SIP response code or a failure reason in events or call records
  • transfer calls; call transfer isn’t available yet

Use TLS for the SIP signalling between Linq and your endpoint. Either form works: a sips: URI, or a sip: URI with ;transport=tls, for example sip:sip.example.com:5061;transport=tls. Linq keeps the ;transport=tls parameter as you set it.

TLS covers the signalling only. The audio flows directly between the phone network and your endpoint, using RTP or SRTP as negotiated in SDP. Linq forwards the SDP unchanged, so the URI scheme doesn’t decide whether the audio uses SRTP.

A sip: URI with no ;transport= is sent over UDP, without TLS. Use it only if your platform doesn’t support TLS.

Use these values whether you run your own SIP server or use a hosted voice-agent platform. A hosted platform’s console may call this an imported number, bring your own number, or an inbound SIP trunk.

Setting Value Why
Phone number If your platform routes on the called number: your Linq number in E.164, including the +, for example +14155550100. Linq puts the called number in the Request-URI (below).
Allowed source addresses and inbound authentication IP-based: allow Linq’s signalling addresses (below). Don’t challenge them with 401 or 407. Linq doesn’t send credentials, so a challenge fails the call. The addresses are shared by every Linq customer.
Transport and port TLS for a sips: URI or a sip: URI with ;transport=tls (recommended). UDP for a sip: URI with no ;transport=, only if your platform doesn’t support TLS. Use the port in your URI; 5060 if there’s none. Linq keeps the URI’s scheme, ;transport= parameter and port.
TLS certificate (sips: or ;transport=tls) A certificate that chains to a public certificate authority and is valid for the host in your URI. TLS 1.2 or later. Linq checks your certificate against the URI’s host.
Address A public IPv4 address: a hostname with an A record, or an IPv4 literal. Use a hostname with TLS. Linq looks up A records. IPv6 and private addresses don’t work.
Request-URI user part (the part before @, including the leading +) The called Linq number in E.164. Linq sets it on each call (below). Route each number to its own agent, and filter out misrouted calls.
Codecs At least one of PCMU, PCMA, G.722, AMR-WB or Opus. Offer G.722, AMR-WB or Opus for HD. The best codec both sides support is used (below).
Media encryption RTP or SRTP, as negotiated in SDP between the phone network and your endpoint. Linq forwards the SDP unchanged. See Encryption.
Media (RTP) addresses Accept audio from the phone network’s media addresses (below), not Linq’s. Advertise a public address in your SDP (the part of the INVITE and its answer that describes the audio). Audio flows directly between the phone network and your endpoint, and Linq doesn’t change the SDP.
Hang-up Linq relays the caller’s BYE to your endpoint. Linq stays in the signalling path for the whole call.
Registration None. Linq sends INVITEs to your URI. Linq doesn’t register, and refuses REGISTER.

On a hosted platform, then point the number at your agent. Some platforms also need your app to accept the call on their side; check your platform’s inbound-call steps.

Linq doesn’t register with your platform and doesn’t send credentials to it. Allow only Linq’s signalling addresses. Those addresses are shared by every Linq customer. Checking the Request-URI user part (your Linq numbers) filters out misrouted calls, but it doesn’t prove a call comes from your Linq account: anyone can create a profile that points at your URI. Don’t let calls that arrive from Linq place outbound calls through your platform.

When you’d use this: create a profile once per agent address, and update it when your agent moves. Allow about 5 minutes before calls reach the new address; calls in progress aren’t affected.

Create a SIP profile with POST /v3/sip-profiles and change it with PUT /v3/sip-profiles/{sipProfileId}. An update changes only the fields you send.

Field Example Notes
name my-voice-agent Required. Keep it to 64 characters or fewer.
primary_uri sips:sip.example.com:5061 Required. The sips: scheme, or sip: with ;transport=tls (or plain sip: for UDP), your host and the port. Don’t include a user part; Linq sets it to the called number on each call. Keep it to 512 characters or fewer.
backup_uri sips:backup.example.com:5061 Optional. Same rules. Linq uses it only if the primary fails.

Your account can have one profile per primary URI. Reuse that profile across your numbers. The assigned_number_count in the response shows how many numbers use it. You can’t delete a profile while it’s assigned to a number. Unassign it first.

See the create and update reference pages for the full request and response. There’s no dashboard screen for SIP profiles yet, so use the API.

Don’t include a user part (the part before @) in your profile URI; Linq sets it to the called number on each call. For a profile URI of sips:sip.example.com:5061, a call to +14155550100 arrives as INVITE 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.

To send your platform extra information with each call, add custom SIP headers to the profile URI as URI headers: after ?, as name=value, joined with &, with each value percent-encoded.

sips:sip.example.com:5061?X-Agent=front-desk&X-Language=en
  • Linq adds these headers to every INVITE it sends to that URI.
  • If you set a backup_uri, add the same headers to it.
  • Header names must start with X-.
  • The headers are fixed for each URI. You can’t set them per call.
  • The headers are part of the URI. They count toward its 512 characters, and two primary URIs that differ only in their headers are different URIs, so each can have its own profile.

Header values are stored on your profile, returned by the API, and sent with every INVITE. Without TLS (a sip: URI with no ;transport=tls) they’re sent unencrypted. Don’t put passwords or API keys in them.

Linq also adds its own X-Linq-Call-Id header to every INVITE, with the call’s id (Matching your call to Linq’s record).

Linq supports PCMU, PCMA, G.722, AMR-WB and Opus. G.722, AMR-WB and Opus are HD (wideband). The best codec that both sides support is used.

A call is HD only when every leg negotiates a wideband codec, so HD is supported but not guaranteed. If your endpoint and the call share no codec, the call fails with 488. If your platform uses a wideband codec not on this list, contact Linq.

Allow SIP signalling from Linq’s addresses, and audio from the phone network’s media addresses.

Contact Linq for the current signalling and media addresses.

If these addresses change, we’ll update this page.

Set backup_uri on your profile. Linq tries it once, and only after the primary fails.

Linq tries your backup when the primary:

  • doesn’t reply to the INVITE within 3 seconds
  • returns 408 or any 5xx
  • doesn’t answer within 30 seconds

Linq doesn’t try your backup when the primary:

  • returns busy or declined (486, 600 or 603)
  • returns any other 4xx, including 480, 487, 404 and 488
  • challenges the INVITE with 401 or 407
  • Each attempt rings for up to 30 seconds. You can’t change the ring time through the API.
  • If the caller hangs up first, the call ends as call_voice.failed with status canceled.
  • With no backup, a primary that doesn’t reply within 3 seconds, or doesn’t answer in time, ends the call as call_voice.no_answer with status no_answer. After a failover, the outcome is the backup’s.
  • If your endpoint challenges the INVITE with 401 or 407, the call ends as call_voice.failed with status failed.
  • A backup whose host is private or doesn’t resolve is skipped, so there’s no failover.

To remove the backup, set backup_uri to an empty string:

Terminal window
curl -X PUT https://api.linqapp.com/api/partner/v3/sip-profiles/{sipProfileId} \
-H "Authorization: Bearer $LINQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"backup_uri": ""
}'

When you’d use this: assign a profile when you bring a number into voice; clear it to stop sending the number’s calls to your agent.

Assign the profile to each number whose calls it should take. Put the number in the path in E.164.

Terminal window
curl -X PUT https://api.linqapp.com/api/partner/v3/phone-numbers/{phoneNumber}/sip-profile \
-H "Authorization: Bearer $LINQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sip_profile_id": "sip_8a3f9c2b1d4e4f5a9b8c7d6e5f4a3b2c"
}'

A 200 response whose sip_profile_id is your profile’s id confirms the assignment. Keep a record of which profile each number has: the API doesn’t return a number’s profile, and GET /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.

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.

To clear a number’s assignment, send null:

Terminal window
curl -X PUT https://api.linqapp.com/api/partner/v3/phone-numbers/{phoneNumber}/sip-profile \
-H "Authorization: Bearer $LINQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sip_profile_id": null
}'

When you’d use this: subscribe once, so your own systems hear about each inbound call as it arrives, rings, is answered and ends.

Subscribe with POST /v3/webhook-subscriptions and an HTTPS URL. You don’t need an extra permission for call events.

Terminal window
curl -X POST https://api.linqapp.com/api/partner/v3/webhook-subscriptions \
-H "Authorization: Bearer $LINQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://webhooks.example.com/linq/voice?version=2026-02-03",
"subscribed_events": [
"call_voice.initiated",
"call_voice.ringing",
"call_voice.answered",
"call_voice.ended",
"call_voice.failed",
"call_voice.declined",
"call_voice.no_answer"
]
}'
  • ?version=2026-02-03 on the URL picks the webhook version. A new subscription without it gets the latest version, which is 2026-02-03.
  • Each URL can have only one subscription. If yours already has one, update it with PUT /v3/webhook-subscriptions/{subscriptionId} and send the full list: your existing events plus the call events. The update replaces the list.
  • Call events use the same signatures and retries as message events. See Verifying signatures with an SDK.

Linq emits call_voice.initiated when an inbound call arrives and is being routed to your endpoint. On an answered call, it is typically followed by call_voice.ringing (only if your endpoint sends 180 or 183), call_voice.answered, then call_voice.ended. Each event carries the call’s id. For each event’s payload, see the Webhook Events reference.

Delivery is best effort. Events can be dropped, arrive out of order or arrive twice. Dedupe on event_id, and treat the event that ends the call as its outcome.

When you’d use this: for call history, to reconcile calls with your own logs, or when you’re missing an event.

List the calls on your number, newest first, with GET /v3/phone-numbers/{phoneNumber}/call-voice. A page holds 50 calls by default and up to 100 with limit. To get the next page, pass next_cursor as cursor.

Terminal window
curl https://api.linqapp.com/api/partner/v3/phone-numbers/{phoneNumber}/call-voice \
-H "Authorization: Bearer $LINQ_API_KEY"

Take a call’s id from that list, from its webhooks, or from the X-Linq-Call-Id header of its INVITE, and fetch the call with GET /v3/call-voice/{callVoiceId}:

Terminal window
curl https://api.linqapp.com/api/partner/v3/call-voice/{callVoiceId} \
-H "Authorization: Bearer $LINQ_API_KEY"

A call record looks like this (trimmed):

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"to": "+14155550100",
"direction": "inbound",
"status": "completed",
"started_at": "2026-03-05T12:00:05Z",
"ended_at": "2026-03-05T12:05:00Z"
}

status is completed, busy, no_answer, failed or canceled. It’s null while the call is in progress. started_at is set on the record and on call_voice.answered. The event that ends the call carries ended_at but not started_at, so read the record for both.

Call your number from a mobile phone for each test. The last column is the webhook event and the call record’s status you should see.

Test Expected result Event / status
A normal call Your agent answers. The INVITE’s Request-URI user part is the called number. The codec is the one you expect, and audio works in both directions. call_voice.answered
Hang up from the mobile phone Your endpoint receives the caller’s BYE. call_voice.ended / completed
Make your primary stop replying (for example, drop Linq’s signalling at its firewall), then call Your backup rings about 3 seconds later. The backup’s outcome; for an answered call, call_voice.ended / completed
Your endpoint returns 486 The call ends. Linq doesn’t try your backup. call_voice.declined / busy
Hang up while your endpoint is ringing Linq cancels the INVITE. call_voice.failed / canceled
Your endpoint shares no codec with the call Your endpoint returns 488. Linq doesn’t try your backup. call_voice.failed / failed

A passing test doesn’t prove the call was HD. Check the negotiated codec.

No call reaches your endpoint and no webhook arrives

Section titled “No call reaches your endpoint and no webhook arrives”

Most likely the call was never routed: when Linq can’t route a call, your endpoint gets nothing and no event is sent. Webhook delivery is best effort, though, so confirm first: list the number’s calls and look for one at the time you called. If there’s a call record, Linq handled the call and the missing event is a webhook delivery problem; check the record’s status in Call outcomes and your webhook subscription. If there’s no record either, the call most likely wasn’t routed. Check these causes:

  • You assigned the number less than 5 minutes ago. Allow about 5 minutes for the assignment to apply, then call again.
  • The profile isn’t assigned to the number. Check the 200 response from your assign request: its sip_profile_id should be your profile’s id. The profile’s assigned_number_count shows how many numbers use it.
  • Your host doesn’t resolve, or resolves to a private or IPv6-only address. Use a hostname with a public A record, or a public IPv4 address.

Your endpoint never sees the INVITE, and you get call_voice.no_answer about 3 seconds later

Section titled “Your endpoint never sees the INVITE, and you get call_voice.no_answer about 3 seconds later”

Or your backup rings instead. A firewall drops Linq’s signalling, nothing is listening on your URI’s host and port, or the host points at the wrong server. Allow Linq’s addresses and check the host and port in your profile.

With TLS (sips: or ;transport=tls), your certificate must chain to a public certificate authority and be valid for the host in your URI. Check the certificate your endpoint presents on the URI’s port.

call_voice.failed, and your platform logged a 404

Section titled “call_voice.failed, and your platform logged a 404”

Your platform doesn’t know the called number. Add the number, including the +, in your platform. See What to enter in your platform.

call_voice.failed right away, and your endpoint logged a 401 or 407

Section titled “call_voice.failed right away, and your endpoint logged a 401 or 407”

Your endpoint challenged Linq’s INVITE. Linq doesn’t send credentials. Turn off the challenge for Linq’s addresses and allow them by IP instead.

The wrong agent answers, or your platform doesn’t recognise the called number

Section titled “The wrong agent answers, or your platform doesn’t recognise the called number”

If your profile URI has a user part, Linq replaces it with the called number. Remove the user part from the profile, and route on the called number in the Request-URI user part. See The Request-URI user part.

Audio from the phone network’s media addresses is blocked, or your SDP advertises a private address. Allow the media addresses and advertise a public address.

call_voice.failed right after your endpoint rejects the call

Section titled “call_voice.failed right after your endpoint rejects the call”

Your endpoint rejected the INVITE with a 4xx other than 408, 480, 486 or 487, or with a 5xx when there was no backup to try. A common cause is a codec mismatch, which returns 488. Offer one of the supported codecs.

That’s the maximum call length. Linq hangs up both sides, and the call ends as call_voice.ended with status completed.

Code When What to do
1001 A required field is missing: name or primary_uri. Add the field.
1005 A URI has no scheme, a bad host, a port outside 1–65535, or a password. Use sips: (or sip:), your host and the port, for example sips:sip.example.com:5061.
2015 Another profile on your account already uses this primary URI, or you tried to delete a profile that’s still assigned. Reuse the existing profile, or unassign the profile first.
2006 The number isn’t yours, or your API key’s environment doesn’t match the number’s. Use a number on your account and an API key from its environment.
2019 On assign: the number or the profile wasn’t found. Check the number (E.164) and the profile id.
2033 The number isn’t published, or it can’t be set up for voice in its current state. Use a published number. If the number is published and you still get 2033, contact Linq.
3006 A temporary failure. The profile usually isn’t assigned. Retry, then confirm the number’s assignment. Contact Linq if it keeps happening.
Webhook event Record status What happened What to check
call_voice.ended completed The call was answered, then hung up (or reached the 4-hour limit). Nothing; this is a normal call.
call_voice.declined busy Your endpoint returned 486, 600 or 603. Whether your agent was busy or set to reject the call.
call_voice.no_answer no_answer Your endpoint returned 480, or didn’t reply within 3 seconds, didn’t answer within the ring time, or returned 408. After a failover, this is the backup’s result. Your firewall, that something is listening on the URI’s host and port, and how fast your agent answers.
call_voice.failed canceled The caller hung up before you answered, or your endpoint returned 487. How fast your agent answers.
call_voice.failed failed Your endpoint rejected the call (for example with 488, 401, 407 or 404), returned a 5xx with no backup to try, or the call failed another way. Codecs, authentication challenges, and your endpoint’s logs.
No event — Most likely the call was never routed. Delivery is best effort, so first list the number’s calls: if there’s a record, the event was lost in delivery and the record’s status is the outcome. No call reaches your endpoint.

After a failover, the outcome is the backup’s. Events and records don’t include the SIP response code or a failure reason. status is the only outcome field.