Custom Number Segment CSV Import Guide: Format Specifications, Detailed Steps, and Best Practices

# Custom Number Segment CSV Import Guide: Format Specifications, Step-by-Step Instructions & Best Practices

In outbound customer acquisition scenarios, batch generating and filtering phone numbers for specific countries and number segments is a high-frequency need. Whether it's screening Telegram for US +1 numbers or targeting China's 138/139 segments for WhatsApp verification, manually entering number segments one by one is not only time-consuming but also error-prone. KK-DATA's **Custom Number Segment CSV Import** feature allows you to upload a CSV file containing fields like country code, prefix, and length. The system automatically generates numbers based on the rules and seamlessly links them with subsequent number screening tasks. This article will fully break down this capability—from format specifications and operational steps to best practices—helping you efficiently complete the "Generate → Screen → Export" pipeline.

## What is Custom Number Segment CSV Import? What Problems Does It Solve?

Simply put, Custom Number Segment CSV Import means users upload a structured CSV file to specify the range of numbers they want to generate on the platform. Each row in the file represents a number segment rule (e.g., country code 1, prefix 2, total length 10 digits). Based on this rule, the system batch-generates all or a specified quantity of numbers under that segment.

Key scenarios this feature addresses include:

- **Regional targeted acquisition**: When promoting in a specific country, such as India (+91), upload only commonly used segments (e.g., starting with 98, 99) to avoid generating invalid numbers.
- **Carrier or campaign targeting**: Some campaigns target only specific carrier segments (e.g., China Mobile's 138, 139). CSV import allows precise limitation.
- **Large-scale, multi-condition combinations**: When generating numbers for multiple countries, prefixes, and lengths simultaneously, CSV files are hundreds of times more efficient than manual entry.
- **Seamless integration with screening tasks**: After generation, submit these numbers directly to Telegram/WhatsApp screening tasks, using the deduplication repository to avoid repeated checks.

**CSV Import** is the core capability of the number generation module. It complements the "Custom Prefix" feature and is better suited for complex, large-scale scenarios.

## Standard Format & Field Descriptions for Custom Number Segment CSV Files

A standard CSV file must include the following columns (header names strictly case-sensitive; it's recommended to download the official template from KK-DATA documentation).

### Required Fields Explained

| Field | Description | Data Type | Example |
|-------|-------------|-----------|---------|
| `country_code` | International dialing code (without +) | Number | 1 (US), 86 (China), 44 (UK) |
| `prefix` | Number prefix (excluding country code) | Number | 138, 2, 7 |
| `length` | Total number of digits of the phone number (excluding country code). For example, Chinese phone 13812345678 without country code 86 is 11 digits, so length=11; US number +1 234567890 without country code 1 is 10 digits, so length=10. | Number | 11 (China), 10 (US) |

**Note**: The length of `prefix` cannot exceed `length`. For example, for China, prefix=138 (3 digits), length=11, remaining 8 digits are randomly generated by the system.

### Optional Fields & Advanced Usage

| Field | Description | Data Type | Example |
|-------|-------------|-----------|---------|
| `start_range` | Starting range of the variable digits after the prefix (optional) | Number | 0 |
| `end_range` | Ending range of the variable digits after the prefix (optional) | Number | 9999 |
| `quantity` | Limit the total number of numbers generated for this segment (optional) | Number | 5000 |

**Advanced Usage**: If both `start_range` and `end_range` are provided, the system generates all numbers within that range (quantity = end_range - start_range + 1), and the `quantity` field is ignored. If only `quantity` is provided, the system randomly picks the specified number from the full range.

For example: UK +44, prefix 7, length=11, start_range=3000, end_range=4000. This generates numbers whose last four digits range from 3000 to 4000, totaling 1001 numbers.

### Common Field Errors & How to Avoid Them

- **Case errors in column names**: Must be lowercase (e.g., `country_code`, not `CountryCode`). It's recommended to copy directly from the official template.
- **Missing fields**: Required columns cannot be omitted; leave optional columns empty (do not fill with `null`).
- **Length conflicts**: If prefix length exceeds length, numbers cannot be generated and the system will show an error.
- **Illegal characters**: Only digits, commas, and newlines allowed; do not add spaces or quotation marks (unless properly escaped per CSV standard).
- **Encoding issues**: Must be UTF-8 without BOM to avoid parsing failures (even though fields contain no Chinese characters, incorrect encoding can cause parsing errors).

> **Format Tip**: It's recommended to download the official CSV template from the console to avoid missing fields or format errors. Template download path: Go to <a href="https://app.kkdata.cc/">KK-DATA Console</a> → Number Generation → CSV Import → Download Template. Or refer to the <a href="https://docs.kkdata.cc/">Documentation</a> section "Custom Number Segment Import".

## Three Steps to Complete Custom Number Segment CSV Import & Number Generation

### Step 1: Prepare and Validate the CSV File

Use Excel or any text editor to create the CSV.

- **Recommended tool**: Edit in Excel, save as CSV (Comma delimited) (*.csv), then open with **Notepad** to verify columns are separated by commas and there is no BOM header.
- **Row limit**: Up to 200,000 rows (segment rules) per upload. There is no limit on the number of numbers generated per segment, but it is recommended that total numbers per task do not exceed 1 million (split into multiple tasks if needed).
- **Validation example**: Create a file with header `country_code,prefix,length` and a single row `1,2,10`. Save and upload for testing.

### Step 2: Upload the CSV to KK-DATA's Generation Module

Log in to the <a href="https://app.kkdata.cc/">KK-DATA Console</a> and go to the "Number Generation" page.

1. Select import mode "CSV Import".
2. Click "Choose File" or drag and drop the CSV file.
3. The system automatically parses and previews the first 10 rows, checking if fields are correctly mapped. If an "unrecognized column name" error appears, go back to Step 1 to verify the header.
4. After confirmation, click "Start Generation".

### Step 3: Set Screening Conditions and Submit the Task

After successful number generation, the page will automatically redirect to the "Number List" or provide a "Continue Screening" button.

- Select the target screening platform: Telegram / WhatsApp / iMessage / RCS.
- Set detection type: e.g., "Valid" or "Active" (can specify active window of 7/15/30 days).
- Optionally use the **Data Deduplication Repository**: The system automatically filters out numbers already in the repository to avoid duplicate charges.
- Confirm estimated cost (see real-time prices in the console). If balance is sufficient, submit the task.

> **Tip**: If the CSV contains multiple countries or different prefixes, one segment per row is supported; the system automatically merges duplicate segments to avoid generating duplicate numbers. It is recommended to split the CSV by country first for easier targeted screening later.

## Differences Between Custom Prefix & Custom Number Segment CSV Import and When to Choose Which

KK-DATA offers two number generation methods: **Custom Prefix** (enter a prefix, select country, set quantity, quickly generate) and **CSV Import**. The decision between them:

| Aspect | Custom Prefix | CSV Import |
|--------|---------------|------------|
| Suitable scenarios | Small quantity, fixed prefix (e.g., only one segment) | Large quantity, multiple segments, multiple countries, with range limits |
| Complexity | Low, enter in the interface | Medium, needs file preparation |
| Number of segments | Up to 10 prefixes at once | Up to 200,000 segment rows at once |
| Range control | Does not support start_range/end_range | Supports precise range or random quantity |
| Best for | Individual ad-hoc tests | Operational teams for batch production |

**Recommendation**: When you need to generate more than 10 segments, or involve multiple countries, or need range control, use CSV Import. If you just need to quickly generate 1–10 fixed-prefix numbers, Custom Prefix is faster.

## Practical Examples: CSV Templates for Three Real Scenarios

### Scenario 1: Generate US (+1) 10-digit numbers starting with 2

File content:

country_code,prefix,length 1,2,10

Rule: US numbers without country code are 10 digits. Prefix 2 is 1 digit. System randomly fills the remaining 9 digits. Number quantity is unlimited (if no quantity or range specified, system generates all combinations, which is huge. It is recommended to add a `quantity` column to limit, e.g., `quantity,10000`).

### Scenario 2: Generate Chinese (+86) 11-digit numbers for multiple segments (139, 138, 137)

File content:

country_code,prefix,length 86,139,11 86,138,11 86,137,11

Each row corresponds to one segment. The system generates numbers for each segment separately. To limit the quantity per segment, add a `quantity` column.

### Scenario 3: Limit generation quantity and range (UK +44, starts with 7, only last four digits 3000-4000)

File content:

country_code,prefix,length,start_range,end_range 44,7,11,3000,4000

In this example, prefix=7 (1 digit), length=11. The system generates numbers where the last four digits range from 3000 to 4000, i.e., 7xxxxx3000 to 7xxxxx4000, total 1001 numbers. The first 6 digits (7xxxxx) are randomly filled, the last four are in fixed range. Note: When `start_range`/`end_range` are provided, the quantity is entirely determined by the range; no need to add `quantity`.

## Common Errors & Troubleshooting Guide

### Error 1: "Unrecognized column name" after upload

- **Cause**: Header name case or spelling error, or presence of invisible characters (e.g., BOM, spaces).
- **Solution**: Copy header from official template; open CSV in Notepad and verify the first line contains only `country_code,prefix,length` (no spaces). If the template includes other optional fields, keep column names exactly as they are.

### Error 2: Generated quantity is 0

- **Cause**: Prefix length + preset range exceeds length limit. E.g., Chinese 11-digit number with prefix=13812345678 (11 digits) leaves no room for additional digits.
- Or missing `country_code` field, or field value is empty.
- **Solution**: Ensure prefix length < length; check that each row in the CSV has complete data.

### Error 3: Parsing timeout after upload

- **Cause**: File too large (over 200,000 rows), or too many fields per row.
- **Solution**: Split the file into multiple uploads; check that each row has the same number of fields.

## From CSV Import to Multi-Platform Number Screening: Complete Pipeline

CSV Import is just the starting point. The best workflow is:

1. **Generate numbers**: Upload CSV → System generates number list.
2. **Submit screening task**: Select Telegram / WhatsApp platform → Set detection type (recommend using "Active" detection first for higher-value numbers) → Bind data deduplication repository → Submit.
3. **Wait for task completion**: Receive notification via Telegram (set in console).
4. **Export results**: After completion, export CSV or TXT files containing screening status (valid/active/gender, etc.) and platform IDs (e.g., tgid, wsid).
5. **Archive data**: Import result numbers into CRM or next marketing tool.

The data deduplication repository works automatically in this process: after each screening task, checked numbers are stored in the repository; subsequent tasks will skip duplicates, saving costs.

## Best Practices: How to Plan CSV Files to Improve Screening Efficiency & Reduce Costs

- **Generate by country and platform**: Screening unit prices may vary per country (check console), and active user distribution differs across platforms. It is recommended to have one CSV file covering only one country's segments for easier submission to different platforms later.
- **Prefer "Active" detection over "Valid"**: Active numbers have much higher acquisition value than valid but inactive ones. Although active detection usually has a slightly higher unit price, the improved conversion rate leads to better overall ROI.
- **Use deduplication repository to avoid duplicate charges**: If the same batch of numbers needs screening on multiple platforms, first run a general detection (e.g., Valid), then submit active detections per platform; the deduplication repository will filter out duplicates.
- **Control single task volume**: Generate no more than 1 million numbers per task. For larger volumes, upload in batches. Large numbers concentrated in one task may extend waiting time; submitting in parts improves flexibility.
- **Keep the original CSV file**: Tag each generation with a task ID for future reference or correlation with screening results.

## Frequently Asked Questions

**Q: What is the maximum number of rows in a CSV file?**  
A: Up to 200,000 segment rows per upload. Each segment can generate multiple numbers. It is recommended that total numbers per task do not exceed 1 million; split into multiple uploads if needed.

**Q: What if the prefix length does not match the length field?**  
A: The system will show an error and reject the upload. Ensure prefix length + remaining variable digits ≤ total length. For example, for Chinese 11-digit numbers, if prefix is "138", length must be 11, and the remaining 8 digits are randomly filled by the system.

**Q: Will numbers in the CSV duplicate numbers from previous tasks?**  
A: KK-DATA provides a data deduplication repository. During the screening phase, it automatically filters out numbers already in the repository. The generation phase does not deduplicate, so it is recommended to submit screening tasks immediately after generation, using the repository to avoid duplicate charges.

**Q: Can I export the original segment list used in CSV import?**  
A: Yes. In the "Number Generation" history, you can download a CSV file containing the original segments and the generated numbers for further analysis and archiving.

**Q: Can Custom Prefix and CSV Import be mixed in one task?**  
A: Mixing in a single task is not currently supported. However, you can first generate numbers via Custom Prefix, export the CSV, and then import it as a segment CSV for a new task to expand further.

---

**Try it now**: Log in to the <a href="https://app.kkdata.cc/">KK-DATA Console</a> to test the Custom Number Segment CSV Import feature, or check the <a href="https://docs.kkdata.cc/">Documentation</a> for the latest format template. For any questions, contact customer support via Telegram <a href="https://t.me/kkdata_cc">@kkdata_cc</a> for one-on-one guidance.