---
title: Quickstart | API Docs
description: 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

- An API key, exported as `LINQ_API_KEY`. See [Authentication](/channel/imessage/getting-started/authentication/index.md).
- A Linq phone number on your account. `GET /v3/phone_numbers` lists 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

1. **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 a `sip:` URI with `;transport=tls`, kept as your platform lists it (for example `sip: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 sends `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.

   Fill in the rest of your platform’s inbound settings from [What to enter in your platform](/channel/voice/getting-started/connect-your-sip-endpoint#what-to-enter-in-your-platform/index.md). Some platforms also need your app to accept the call on their side, so check your platform’s inbound-call steps.

2. **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 `201` response. Its `id` starts with `sip_`. Export it for step 3 with `export 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 with `GET /v3/sip-profiles` and reuse its `id`.

3. **Assign it to your number**

   Send the profile’s `id` to `PUT /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 `200` response with your `phone_number` and a `sip_profile_id` equal to your profile’s `id`. 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.

   **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                                                        |
   | ---------------------------------------------------------- | -------------------------------------------------------------------- |
   | [`2033`](/channel/imessage/error/codes/2xxx/2033/index.md) | The number isn’t published, or can’t be set up for voice.            |
   | [`2006`](/channel/imessage/error/codes/2xxx/2006/index.md) | The number isn’t yours, or your API key is from another environment. |
   | [`2019`](/channel/imessage/error/codes/2xxx/2019/index.md) | The number or the profile wasn’t found.                              |

### Before you call

- [ ] The assign request in step 3 returned `200` with your profile’s `id`.
- [ ] Your firewall allows [Linq’s addresses](/channel/voice/getting-started/connect-your-sip-endpoint#allow-linqs-addresses/index.md).
- [ ] 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](/channel/voice/getting-started/connect-your-sip-endpoint#call-events-webhooks/index.md) first, so a failed call leaves an event as well as a `status`.

4. **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 `From` header.

   To find the call afterwards, list your number’s calls and fetch one by its `id`; see [Find a call](/channel/voice/getting-started/connect-your-sip-endpoint#find-a-call/index.md).

## 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](/channel/voice/getting-started/connect-your-sip-endpoint#find-a-call/index.md), then look it up in [Call outcomes](/channel/voice/getting-started/connect-your-sip-endpoint#call-outcomes/index.md).
- **Your platform saw no INVITE:** check that the `200` from step 3 showed your profile’s `id`, and that `assigned_number_count` in `GET /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

- [How calls work for your agent](/channel/voice/getting-started/how-calls-work/index.md): what Linq decides on a call, what you decide, and the logic to build around calls.
- [Connect your SIP endpoint](/channel/voice/getting-started/connect-your-sip-endpoint/index.md): call webhooks, a backup endpoint, codecs, custom SIP headers and every setting.
- [Outbound calling (early access)](/channel/voice/guides/outbound-calling/index.md): place calls from your Linq numbers through Linq.
- [SIP Profiles API reference](/channel/imessage/api/resources/sip_profiles/index.md)
