Recipes

Dynamic Number Insertion (DNI), also called number swapping, dynamically displays a unique tracking number to each website visitor based on how they reached your site. When that number is called, Convirza ties the call back to the visitor's referring source and session data, including URL parameters, GCLID, and the keywords they searched, so you can attribute phone calls to the marketing that drove them.

Time to complete: about 20 minutes (URL or Source based). Session-based DNI needs a number pool, which may require a quick request to Convirza Support.

You can set DNI up two ways:

In the platform (CAI) — point and click, no code. Best for one-off setup. (Steps 2 to 6 below.)

By API — provision and configure DNI programmatically, so you can automate it across many numbers or build it into your own product. (See "Configure DNI by API" below.)

Either way, you finish by deploying a small script on your site (Step 4) and reading the attributed call data (Step 7).

Base URLs

Service	Base URL
OAuth (get and refresh tokens)	`https://platform-oauth.convirza.com`
Public API (all business endpoints)	`https://platform-api.convirza.com/v3`

Every example below uses these. Pass Authorization: Bearer <access_token> on every API request.

How It Works

Ad / referral / search
        |
        v
Visitor lands on your page   ->   DNI script reads the source
(referrer + URL parameters: gclid, utm_*, custom keywords)
        |
        v
Script swaps your number for a tracking number (numbers wrapped in your HTML class)
        |
        v
Visitor calls the tracking number
        |
        v
Convirza ties the call to the session
(source / keyword / first + last page / geo / caller)
        |
        v
Read it via the API or send it to Google Analytics / Google Ads as a conversion

Choose Your DNI Type

DNI comes in three varieties. Pick the one that matches your goal:

URL-based — assigns a unique number per URL. Best for tracking specific links in email and social campaigns. Uses the reserved HTML class lmc_track.

Source-based — assigns one number per referring source (Google, Bing, Facebook). Best for high-level metrics on low-traffic sites.

Session-based — assigns a unique number to every visitor for the duration of their session. The most granular option; captures keywords and full session detail. Requires a number pool.

Step 1: Size Your Number Pool (session-based only)

A number pool is a set of numbers assigned and reused across concurrent visitors. Size it with this formula, then round up:

pool = ceil( ( Peak hourly visitors in the last 90 days / (60 / Avg session minutes) ) * 1.3 )

Example: 100 peak hourly visitors, 2.5 minute average session:
(100 / (60 / 2.5)) * 1.3 = (100 / 24) * 1.3 = 5.4 -> round up to 6 numbers.

Find both inputs in Google Analytics under Audience > Overview (use the Hourly view for peak visitors, and Avg. Session Duration for session length).

Configure DNI in the platform (CAI)

Step 2: Add a Tracking Number in CAI

In the platform, start a new tracking number:

Single Number (source-based or URL-based): choose a number from the dropdown and fill in Tracking Number Name, Ring to Number, and your usual fields.

Number Pool (session-based): choose an area code or toll-free prefix and enter a quantity of 1. Then contact Convirza Support to increase the pool to the size you calculated in Step 1.

Step 3: Enable Dynamic Number and Configure Settings

Expand Advanced Tracking Number Settings and toggle the Dynamic Number checkbox. Then configure:

Setting	What it does
Host Domain	Limits the script to one domain, or use `.` to allow it on any domain.
Referring Website	When the dynamic number should show (for example, Google Paid Ads).
DNI Type	Session for a number pool; Source or URL for a single number.
HTML Class	The class used to wrap your phone numbers and trigger the swap. Use an identifiable prefix such as `cvz_adwords`. For URL-based DNI you must use `lmc_track`.
Keyword (session and source)	Swaps the number when a URL parameter is present. Example: keyword `TestDNI:ABC` swaps for `https://www.convirza.com/?TestDNI=ABC`.
Identifier	A placeholder string (letters and/or numbers, for example `1234567890`) that, wherever it appears on the page, is replaced by the tracking number.
Number Format	How the tracking number is displayed.

Save the number.

Configure DNI by API

Prefer to automate? You can provision a tracking number and configure its DNI swap behavior in a single V3 call, instead of using Steps 2 and 3. This is ideal for setting up DNI across many numbers or building it into your own product.

DNI configuration is part of the V3 Provisioned Routes API. A provisioned route carries the tracking number, its routing, and its DNI settings together. See Create Provisioned Route in the API reference for the full schema.

Stage A — Authenticate. Exchange your credentials for an access token:

Stage B — Create the route with DNI settings (one call). Provision the tracking number, its routing, and the DNI swap behavior in a single request:

Required fields: provisioned_route_name, org_unit_id, routing_configuration, phone_numbers. Find numbers to assign with Search Phone Numbers / Search Reserved Numbers, and your org_unit_id with List Child Groups.

Session-based number pools: size the pool with the Step 1 formula and create it in the platform (Step 2) for now. The V3 Create Provisioned Route schema does not currently expose a documented number-pool object, so session pools are set up in CAI; the dni_settings above still apply. URL-based and source-based DNI need only the single-number call above.

Platform setting → API field (V3 `dni_settings`)

The platform labels and the V3 dni_settings fields are the same concepts under different names. Unlike the platform, the V3 API exposes every one of these directly — including Keyword, Identifier, and Number Format:

Platform setting (Step 3)	API field	Notes
HTML Class	`dni_element`	CSS selector for the elements wrapping your numbers, e.g. `.cvz_adwords`; use `.lmc_track` for URL-based.
Referring Website	`referrer` (+ `referrer_type`)	Domain the visit was referred from; `referrer_type` e.g. `paid`.
Host Domain	`destination_url`	The domain the script runs on.
DNI Type	`dni_type`	e.g. `session`, `source`, `url`.
Keyword	`dni_keywords`	Comma-separated keywords that trigger the swap.
Identifier	`identifier`	Placeholder string replaced by the tracking number, e.g. `PHONE_NUMBER`.
Number Format	`dni_number_format`	Display format, e.g. `(xxx) xxx-xxxx`.
Keep-alive / session length	`dni_ttl`	Minutes to hold a session's number before recycling.
(URL parameters to capture)	`custom_cookie`	Comma-separated params, e.g. `utm_source,utm_medium,utm_campaign`.
(organizational group)	`org_unit_id`	Your group ID. Use List Child Groups to find it.

Step 4: Deploy the DNI Script

Go to Settings > Customization > DNI. You'll see the DNI numbers configured for the current group.

Click Copy Code and copy the JavaScript shown under Step 1.

Paste it into the <head> section of every page where your numbers should swap.

On a template-based site (for example WordPress), add it once to your theme's header.php using a child theme or a plugin.

No access to the site code? Deploy the header script with Google Tag Manager instead.

Step 5: Wrap the Numbers You Want to Swap

Wrap each phone number in your HTML class so the script can find and replace it:

For click-to-call links, put the class on the same element as the href:

To run multiple DNI types in one place (for example source and session together), list the classes in sequence:

For URL-based DNI, add the lmc_track parameter followed by the tracking number to the links you build:

http://www.website.com/page.html?lmc_track=(888) 627-7470

No access to your site's HTML? Set the HTML Class to * when configuring the number and every phone number on the page swaps automatically, with no class needed. This does not work for URL-based DNI; use Google Tag Manager for that. You can also use the Identifier field instead of a class: put the identifier string on the page and it gets replaced by the tracking number.

Step 6: Verify the Swap

Open your page with a test source, for example https://yoursite.com/?utm_source=google&gclid=TEST123.

Confirm the displayed number and any tel: link changed to a tracking number.

Call that number, then confirm the call appears in Convirza with the captured source and keyword.

Common pitfalls: page caching can serve a stale number (exclude the DNI script from caching and minification); the script must be in the <head>; Safari ITP and ad blockers can drop the session, which shows up as Direct/Unknown for a share of traffic.

Step 7: Use the Data (API and conversions)

Once calls are flowing, consume the attributed data programmatically.

Read a single call with its DNI data (Get Call By ID). Add include=dni_data to embed the DNI tracking module (web session, location, UTM params, referral data):

List calls with their DNI data (Get Calls List). The same include parameter works on the list endpoint; limit is required (1–200) and the date range defaults to the last 7 days:

include accepts multiple modules, e.g. ?include=dni_data,scorecard,tags.

Or receive each call in real time on a webhook by subscribing to call events (see Create Webhook in the API reference).

Then close the loop by sending conversions to your ad platform:

Google Analytics — native integration; mark phone calls as a goal/conversion.

Google Ads — import call conversions with the GCLID, or via Enhanced Conversions for Leads when no GCLID is present.

Microsoft Ads — push call conversions.

What You Can Measure

DNI surfaces, per call: marketing channel / source / keyword, the first and last webpage the caller viewed, geo-location, total calls, call duration, caller ID, and caller information, plus lead quality when paired with Conversation Analytics.

Troubleshooting

Symptom	Likely cause	Fix
Number does not swap	Page caching, script not in `<head>`, or missing HTML class	Exclude DNI from caching/minification; confirm the script is in the head; confirm the number is wrapped in your HTML class
URL-based DNI not swapping	Wrong HTML class	URL-based DNI must use the class `lmc_track` and the `lmc_track` URL parameter
Calls show Direct / Unknown	Safari ITP or an ad blocker dropped the session	Expected for a share of traffic
Two visitors share a number	Number pool too small	Recalculate with the Step 1 formula and contact support to increase the pool
Google Ads conversions missing	GCLID is case-sensitive; conversion renamed; 24-48 hour lag	Do not lowercase the GCLID; keep the conversion name; allow up to 48 hours
API: `401 Unauthorized`	Token expired (access tokens last 7 days)	Refresh with the Refresh Access Token endpoint
API: `400` on `/provisioned-routes`	Missing a required field (`provisioned_route_name`, `org_unit_id`, `routing_configuration`, `phone_numbers`)	Supply all four required fields; put DNI config in the `dni_settings` array on the same request
API: `403 Forbidden` on create	ReadOnly user	Creating routes requires an `Admin` or `Standard` role

Next Steps

Provision a Number

Get Your Bearer Token

Send Call Conversions to Google Ads

Set Up DNI with Google Tag Manager

Need help sizing a pool or expanding one? Convirza Support: support@convirza.com, 855-889-3939.

Set Up Dynamic Number Insertion (DNI)

Base URLs#

How It Works#

Choose Your DNI Type#

Step 1: Size Your Number Pool (session-based only)#

Configure DNI in the platform (CAI)#

Step 2: Add a Tracking Number in CAI#

Step 3: Enable Dynamic Number and Configure Settings#

Configure DNI by API#

Platform setting → API field (V3 dni_settings)#

Step 4: Deploy the DNI Script#

Step 5: Wrap the Numbers You Want to Swap#

Step 6: Verify the Swap#

Step 7: Use the Data (API and conversions)#

What You Can Measure#

Troubleshooting#

Next Steps#