---
title: Connect your SIP endpoint | API Docs
description: 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](/channel/voice/getting-started/quickstart/index.md).

**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](/channel/voice/guides/outbound-calling/index.md) (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

## Encryption

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.

## What to enter in your platform

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](#the-request-uri-user-part)).                          |
| Allowed source addresses and inbound authentication                    | IP-based: allow Linq’s signalling addresses ([below](#allow-linqs-addresses)). 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](#the-request-uri-user-part)).                                                                                                                 | 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](#codecs-and-hd-audio)).                                     |
| Media encryption                                                       | RTP or SRTP, as negotiated in SDP between the phone network and your endpoint.                                                                                                                                    | Linq forwards the SDP unchanged. See [Encryption](#encryption).                                                |
| Media (RTP) addresses                                                  | Accept audio from the phone network’s media addresses ([below](#allow-linqs-addresses)), 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.

### Protect your endpoint

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.

## Values to configure at Linq

**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](/channel/imessage/api/resources/sip_profiles/methods/create/index.md) and [update](/channel/imessage/api/resources/sip_profiles/methods/update/index.md) reference pages for the full request and response. There’s no dashboard screen for SIP profiles yet, so use the API.

### The Request-URI user part

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:+14155550100@sip.example.com: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.

### Custom SIP headers

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](/channel/voice/getting-started/how-calls-work#matching-your-call-to-linqs-record/index.md)).

## Codecs and HD audio

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 Linq’s addresses

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.

## Add a backup endpoint (failover)

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:

- [cURL](#tab-panel-0-0)

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": ""
    }'
```

## Assign numbers

**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.

- [cURL](#tab-panel-1-0)

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`:

- [cURL](#tab-panel-2-0)

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
    }'
```

## Call events (webhooks)

**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](/channel/imessage/guides/webhooks#verifying-signatures-with-an-sdk/index.md).

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](/channel/imessage/api/resources/webhooks/index.md).

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.

## Find a call

**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`.

- [cURL](#tab-panel-3-0)

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}`:

- [cURL](#tab-panel-4-0)

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.

## Test call checklist

Call your number from a mobile phone for each test. The last column is the [webhook event](#call-events-webhooks) and the call record’s [`status`](#find-a-call) 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.

## Common issues

### 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](#find-a-call) 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](#call-outcomes) and your [webhook subscription](#call-events-webhooks). 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](#assign-numbers): 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

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](#allow-linqs-addresses) and check the host and port in your profile.

### Your endpoint logs a TLS handshake error

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`

Your platform doesn’t know the called number. Add the number, including the `+`, in your platform. See [What to enter in your platform](#what-to-enter-in-your-platform).

### `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

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](#the-request-uri-user-part).

### No audio, or audio in one direction only

Audio from the phone network’s media addresses is blocked, or your SDP advertises a private address. Allow the [media addresses](#allow-linqs-addresses) and advertise a public address.

### `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](#codecs-and-hd-audio).

### The call drops at exactly 4 hours

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

## Errors and what to do

### API errors during setup

| Code                                                       | When                                                                                                                   | What to do                                                                                 |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`1001`](/channel/imessage/error/codes/1xxx/1001/index.md) | A required field is missing: `name` or `primary_uri`.                                                                  | Add the field.                                                                             |
| [`1005`](/channel/imessage/error/codes/1xxx/1005/index.md) | 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`](/channel/imessage/error/codes/2xxx/2015/index.md) | 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`](/channel/imessage/error/codes/2xxx/2006/index.md) | 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`](/channel/imessage/error/codes/2xxx/2019/index.md) | On assign: the number or the profile wasn’t found.                                                                     | Check the number (E.164) and the profile `id`.                                             |
| [`2033`](/channel/imessage/error/codes/2xxx/2033/index.md) | 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`](/channel/imessage/error/codes/3xxx/3006/index.md) | A temporary failure. The profile usually isn’t assigned.                                                               | Retry, then confirm the number’s assignment. Contact Linq if it keeps happening.           |

### Call outcomes

| 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](#find-a-call): if there’s a record, the event was lost in delivery and the record’s `status` is the outcome. | [No call reaches your endpoint](#no-call-reaches-your-endpoint-and-no-webhook-arrives).                 |

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.

## Related

- [How calls work for your agent](/channel/voice/getting-started/how-calls-work/index.md)
- [Quickstart](/channel/voice/getting-started/quickstart/index.md)
- [SIP Profiles API reference](/channel/imessage/api/resources/sip_profiles/index.md)
- [Call Voice API reference](/channel/imessage/api/resources/call_voice/index.md)
- [Webhook Subscriptions API reference](/channel/imessage/api/resources/webhook_subscriptions/index.md)
- [Webhooks guide](/channel/imessage/guides/webhooks/index.md)
- [Error codes](/channel/imessage/error/index.md)
- [Outbound calling (early access)](/channel/voice/guides/outbound-calling/index.md)
