Telnyx Integration - Setup Guide

Overview

PracBill integrates with Telnyx to automatically import Call Detail Records (CDR), create customer accounts, and manage billing based on your Telnyx account structure.

If you are a Telnyx reseller using Managed Accounts, each Managed Account can be mapped to a customer in PracBill for automated billing — including full wholesale/reseller billing where both you (the reseller) and your end-customers are billed correctly.

This guide covers everything needed to set up the integration.

How the Integration Works

PracBill connects to Telnyx via API to:

• Import CDR — Call records are pulled automatically and matched to the correct customer

• Sync Customers — Billing Groups within Managed Accounts are mapped to PracBill customer records

• Track Services — Connections and phone numbers are created as services against each customer

• Wholesale Billing — When using Managed Accounts, CDR is imported into the reseller's department for reseller billing, while customers and services are created in the child department with wholesale-linked service types so both parties are billed correctly

• Detect New Accounts — When a new Managed Account appears that PracBill hasn't seen before, you will be notified by email so it can be onboarded

• Email Notifications — When a new customer is auto-created from a Telnyx billing group, an email is sent to the department's billing email address so staff can review and update the customer's details

How Reseller / Wholesale Billing Works

If you are a Telnyx reseller with Managed Accounts, PracBill sets up a two-level billing structure automatically:

The Hierarchy

How It Works

1. CDR imports into the parent department — This ensures you (the reseller) are billed for all usage across the managed account

2. Customers are created in the child department — Each Billing Group becomes a customer in the child department, with their connections and phone numbers as services

3. Wholesale service types link both levels — The child department's service types are wholesale-linked to the parent department's service types. When a service is created in the child department, PracBill automatically creates a matching service in the parent department under the reseller customer

4. Both invoices are generated correctly — The child department invoices the end-customer, and the parent department invoices the reseller

What This Means For You

• You don't need to manually create services in two places

• Adding a new connection or phone number in Telnyx will automatically create services at both the reseller and end-customer level

• Billing is kept in sync across both departments

How Customer Auto-Creation Works

PracBill automatically creates customers based on your Billing Groups in Telnyx.

Billing Group to Customer Mapping

• Each Billing Group becomes a separate customer in PracBill

• All connections assigned to a billing group are linked to that customer

• If a Managed Account has only one billing group, all connections (even those not explicitly assigned) are automatically grouped under it

• Phone numbers assigned to each connection are discovered and created as individual services

When a New Customer is Created

When a billing group is detected that doesn't already exist in PracBill:

1. A new customer record is created with the billing group name as the company name

2. All connections under that billing group are mapped to the customer

3. Engineering (service) records are created for each connection and its phone numbers

4. An email notification is sent to the department's billing email address

Email Notification

The notification email includes:

• Customer name and ID

• Department name

• Billing Group ID

• List of all connections assigned to the customer

• A direct link to the customer record in PracBill

Action Required: When you receive this email, please review the new customer and update their details — including address, contact information, and billing preferences. The auto-created record will only have the company name populated.

Connections Without a Billing Group

If a connection has no billing group and the Managed Account has multiple billing groups, PracBill will report the unassigned connection in the import log rather than creating a customer for it. You should assign the connection to a billing group in the Telnyx portal, and it will be picked up on the next sync.

Supported Telnyx Service Types

PracBill automatically creates service types for the following Telnyx products. Each connection is matched to the correct service type based on its usage in CDR data:

These service types are created automatically on first import — no manual setup is required.

Initial Setup

Step 1: Provide Your Master API Key

We need your Telnyx V2 API Key from your master (manager) account. This allows PracBill to discover your Managed Accounts.

How to Generate a V2 API Key

1. Log in to the Telnyx Mission Control Portal at https://portal.telnyx.com

2. Go to Account → Keys & Credentials

3. Under API Keys, click Create API Key

4. Give the key a descriptive name, e.g. PracBill Integration

5. Copy the generated API key — you will only see it once

6. Provide the key to us securely

The key format starts with KEY followed by a long string (e.g., KEY019C45A6...).

Step 2: Generate API Keys for Each Managed Account

The master API key can discover your Managed Accounts but cannot access their resources (connections, billing groups, phone numbers, or call records). Each Managed Account needs its own V2 API key.

How to Generate a Managed Account API Key

1. Log in to the Telnyx Mission Control Portal

2. Navigate to Account → Managed Accounts

3. Click on the Managed Account you want to configure

4. Once inside the Managed Account view, go to Account → Keys & Credentials

5. Under API Keys, click Create API Key

6. Name the key PracBill Integration

7. Copy the generated API key

8. Record which Managed Account the key belongs to

Repeat this for every Managed Account you want integrated.

Provide the Keys

Please fill in and return the following:

Step 3: Confirm Your Billing Groups

Billing Groups in Telnyx let you categorise usage and invoice records. PracBill uses Billing Groups to create customers — each Billing Group becomes a customer.

How to View Your Billing Groups

1. Log in to the Telnyx Mission Control Portal

2. Navigate to Account → Managed Accounts

3. Click into each Managed Account

4. Go to Billing → Billing Groups

5. Note down each Billing Group name

Provide the Billing Groups

Important: If a Managed Account has only one billing group, all connections will be automatically assigned to it — even if they are not explicitly linked in Telnyx. If there are no billing groups, please create at least one to ensure proper customer mapping.

Step 4: Assign Connections to Billing Groups

For best results, make sure each connection in Telnyx is assigned to the correct billing group:

1. Go to Networking → SIP Connections (or IP Connections) in the Telnyx portal

2. Click on each connection

3. Under the connection settings, assign it to the appropriate Billing Group

If a connection is not assigned to any billing group and the account has multiple billing groups, PracBill will flag it in the import log for you to resolve.

Ongoing: What Happens Automatically

Once set up, the following happens automatically on each import cycle:

Ongoing: Adding New Managed Accounts

When you create a new Managed Account in Telnyx after the initial setup, PracBill will detect it automatically during the next sync and flag it as an unknown managed account.

What Happens

1. PracBill detects a Managed Account ID that is not yet mapped to a customer

2. An email notification is sent alerting you to the new account (throttled to one alert per account every 3 days)

3. No CDR data will be imported for that account until it is onboarded

What You Need To Do

For each new Managed Account:

1. Generate a V2 API Key for the new Managed Account (follow the steps in Step 2 above)

2. List any Billing Groups configured under the new account

3. Provide both to us so we can add it to the integration

4. Confirm your customer mapping preference for the new account

Until the API key is provided and the account is configured, call records for that Managed Account will not be imported.

Required API Key Permissions

If you restrict API key permissions, each key must have at minimum:

If in doubt, a full-access read-only key is the simplest option.

Security

• API keys are stored securely and only used for read-only API access

• Keys can be revoked at any time from the Telnyx portal — let us know if you regenerate a key so we can update the configuration

• We recommend creating dedicated keys named PracBill Integration so they are easy to identify and manage

• Never share API keys over unencrypted channels — use a secure method (e.g., password manager sharing, encrypted email)

Troubleshooting

Questions?

If you're unsure about any of these steps, contact us and we can arrange a screen-share session to walk through the process together.