tg US data export specifications: CSV/TXT column names, encoding, delimiters and downstream import best practices

#tgUS data export specifications: CSV/TXT column names, encoding, delimiters and downstream import best practices

In cross-border marketing and Telegram community operations, tg US data (that is, US number-related data detected through the number screening platform) is the core resource to accurately reach North American users. After many teams get the exported files, the data cannot be imported into CRM or private messaging tools due to mismatched formats, coding errors or field misalignments, wasting time and budget. This article will explain in detail the export format specifications of tg US data on the KK-DATA platform, including the meaning of CSV/TXT column names, UTF-8/GBK encoding selection, comma and tab delimiter switching, and how to smoothly import TG US number data into downstream business systems to avoid garbled characters and field misalignment.

What is tg US data? Why do we need a standardized export format?

tg US data refers to the result set obtained after testing the US mobile phone number segment through the Telegram number screening task. Detection types can include: whether the number has opened Telegram (registration detection), activity level (the most recent online window can be specified), gender (including age, avatar and other public inference fields), and TGID (Telegram user’s unique identifier), etc. Combined, these fields form TG US number data that can be used for precision marketing.

The standardized export format is crucial - Field order, encoding, delimiter If there is any problem in any link, the downstream tools will not be able to parse it normally. For example:

When UTF-8 encoded CSV is opened directly with Excel for Windows, Chinese characters may become garbled;
The field contains commas and the CSV is not escaped correctly, resulting in misaligned columns;
The export column names are inconsistent with the CRM system field mapping, and the data is confusing after import.

Therefore, understanding the details of the export format is the first step to using tg US Data efficiently.

What typical fields does tg US data contain?

tg US data exported by the KK-DATA platform, common column names and meanings are as follows (fields may increase or decrease due to different detection types, subject to actual export by the console):

Column name example	Meaning description	Purpose
`PhoneNumber`	Mobile phone number (including country code, such as +1xxxxxxxxxx)	Basic field, used for matching or importing
`TelegramActive`	Whether active (may return “Yes/No” or “1/0”)	Filter active users
`TelegramGender`	Inferred gender (Male/Female/Unknown)	Gender orientation
`Age`	Inferred age (e.g. 30, 25-34)	Age-stratified targeting
`TGID`	Telegram user ID	Accurate reaching or deduplication
`CountryCode`	Country code (such as US)	Regional filtering
`LastSeen`	Last online time	Active window verification

Note: Gender and age fields are inferred based on public information, are not 100% accurate, and cannot be used for identity verification. Missing values (empty) represent unrecognizable values and do not affect the use of other fields.

Common problems caused by non-standard export

Garbled characters: Encoding mismatch, Chinese/special characters are displayed abnormally.
Field misalignment: The number contains commas or quotation marks, and the CSV is not escaped correctly, causing the content of one column to be split into multiple columns.
Import failed: The CRM or EDM tool has strict restrictions on column names and delimiters. If they do not match, the import will be refused.
Duplicate Data: Numbers exported from multiple tasks are not filtered, causing repeated deductions and affecting subsequent analysis.

Detailed explanation of CSV and TXT export formats: column names and delimiters

The KK-DATA platform supports two export formats, CSV and TXT. The column name order and content are the same, but the delimiters are different:

CSV: By default, comma (,) is used as the separator, and the first line is the column name. Suitable for most data processing tools and database imports.
TXT: By default, the tab character (\t) is used as the delimiter, and the first line is also the column name. Suitable for certain versions of Excel or when field content contains commas.

Standard column names and corresponding order (take CSV as an example)

The first row and column names of the exported CSV file are as follows (example, the actual control is based on the console):

PhoneNumber,TelegramActive,TelegramGender,Age,TGID,CountryCode,LastSeen

Each row of data corresponds to the detection result of a number. If there is no data in a field (for example, gender is not identified), the cell will be empty.

Delimiter selection and considerations

Comma Separated (CSV): The most common, but you need to pay attention to whether the field content itself contains commas (for example, “25-34” may not, but some text fields may contain commas). KK-DATA will automatically add double quote escaping to fields containing commas or quotes when exporting. Downstream tools must support standard CSV escaping rules.
Tab delimited (TXT): avoid comma conflicts, especially suitable for scenarios with complex field content. However, some tools (such as Excel that directly opens TXT) may require manual selection of delimiters.

Best Practice: If the downstream tool has good CSV support, use CSV first; if the number or field content may contain commas (such as the memo field), it is recommended to switch to TXT format.

Preview separators before exporting

On the KK-DATA task export page, you can select “CSV (comma)” or “TXT (tab)” and view the sample lines to confirm that the delimiter is correct before downloading.

Encoding choice: UTF-8 or GBK? How to avoid garbled characters?

Encoding issues are the most common export pitfalls. tg US data mainly contains English and numbers, but the gender field may contain Chinese (such as “male/female”), and the age field may also have Chinese descriptions (such as “about 30 years old”). Therefore encoding settings directly affect readability.

Encoding type	Applicable scenarios	Precautions
UTF-8 (no BOM)	Linux/Mac system, Web backend, most databases	Directly opening with Excel may cause garbled characters
UTF-8 with BOM	Windows version of Excel, some Chinese CRM	Excel can automatically recognize UTF-8
GBK (GB18030)	Domestic old systems, some Chinese customized CRMs	International software compatibility is poor, it is recommended to avoid

Recommended practices

Mainly used in China: Select “UTF-8 with BOM” encoding when exporting. When Excel for Windows opens UTF-8 CSV, the BOM mark in the header of the file allows Excel to correctly identify the encoding and avoid garbled characters.
International Tools or Mac/Linux: Select “UTF-8 (No BOM)”, and then process it with VS Code, Notepad++ or command line tools.
If garbled characters appear: After downloading, open it with Notepad++, click “Encoding” → “Convert to UTF-8 encoding”, save and reopen; or use Excel’s “Data” → “Import from text/CSV” to manually select UTF-8 encoding and comma separation.

NOTE: Field content may contain special characters

Some fields (such as TGID, gender tag) may contain commas or quotation marks. When exporting, you can prefer tab-delimited (TXT format) or ensure that CSV uses correct escape. If fields are misaligned, try re-exporting in TXT format.

How to import tg US data into CRM, EDM or private messaging tools?

After getting the standardized export file, the import steps are generally as follows:

Data preparation: According to the tool requirements, select CSV or TXT, UTF-8 or GBK encoding. If deduplication is required, first process it in the data deduplication warehouse of the KK-DATA platform, or use Python/Excel to deduplicate it yourself.
Field mapping: Map export column names to fields of the target system. For example, the “mobile phone number” of the CRM system is mapped to PhoneNumber, and the “active status” is mapped to TelegramActive.
Small batch test: First import 50~100 records and confirm that the field values are correct, no garbled characters, and the format matches.
Batch import: After confirmation, complete the import.

Field mapping example: CRM system import

Assuming that the CRM you are using supports custom fields, you can do the following mapping:

CRM fields	Export column names	Notes
Mobile phone number	`PhoneNumber`	Required, usually a unique identifier
Customer Tags	`TelegramActive` + `TelegramGender`	Combine active status and gender into tags
Age segmentation	`Age`	Create groups or labels by age group
TG user ID	`TGID`	If supported by CRM, it can be used as a backup ID

Suggestions for importing private messaging tools (such as Telegram Bot)

For private messaging tools based on Telegram Bot, the TGID field is the most accurate way to reach it, because the number may have format differences or may have been deleted. Therefore:

Give priority to exporting task fields containing TGID;
When importing the private message tool, map TGID to the “User ID” column;
If you need to filter by gender/age, it is recommended to set filter conditions (such as “Gender=Male”) in advance when submitting the filter task. The exported results have been filtered to avoid repeated processing in the future.

Notes on performance and limitations when exporting tg US data in batches

Maximum number of items for a single task: about 1 million (subject to the actual display on the console). Submit in batches more than recommended.
Export file size: Taking 1 million records as an example, the CSV file may reach tens of MB. Pay attention to network stability when downloading. It is recommended to use a browser that supports resumed downloads, or obtain it directly through the API (if available).
Browser compatibility: Chrome, Edge, and Firefox are all available. Safari may trigger encoding problems when downloading large CSVs. It is recommended to use Chrome.
Export frequency: There is no hard limit, but it is recommended to arrange tasks reasonably to avoid generating too many large files at one time.
Balance Deduction: Deduction based on the actual number of detected items, and the export itself is free. You can check the detected quantity and estimated cost through “Task Details” in the console.

FAQ

**Q: After exporting tg US data, what should I do if it is all garbled when opened in Excel? **

Answer: Most of the reasons are encoding mismatch. It is recommended to select UTF-8 with BOM encoding when exporting; if it has been downloaded, you can use Notepad++ to open it, menu “Encoding” -> “Convert to UTF-8 encoding”, save and then open it with Excel. Or directly use Excel’s “Data” -> “Import from Text/CSV” and select UTF-8 and comma delimiters.

**Q: Does the “Telegram Gender” field in the exported file contain gender data for all users? **

Answer: The gender field is inferred based on the Telegram public information associated with the number and is not 100% covered. Missing values (empty) indicate unrecognizability and do not affect the use of other fields. The same applies to the age field (Age). It is inferred data and cannot be used as an accurate value at the ID card level.

**Q: CSV or TXT format, which one is more suitable for importing Facebook ad custom audiences? **

Answer: Facebook Custom Audiences usually require CSV format, UTF-8 encoding, comma delimitation and column names in the first line. It is recommended to export the CSV format and keep only the two columns PhoneNumber (required) and CountryCode (optional), delete other non-required columns, and then upload.

**Q: After exporting TG US data, I found that some numbers are duplicated from previous tasks. What should I do? **

Answer: KK-DATA provides a data deduplication warehouse, which can enable the “duplication” function when submitting new screening tasks to avoid repeated detection and deductions. Exported files can be processed by yourself using Python (pandas) or Excel’s “Remove Duplicates”.

**Q: The number of rows in the exported file is inconsistent with the number of queries I submitted. Is it missing? **

Answer: After the screening task is completed, the actual number of test results returned may be less than the number submitted (invalid numbers, blocked, etc.), and the balance will be deducted based on the actual number of tests. The export file only contains “detection completed” records and does not contain unprocessed or invalid numbers. You can view the “Detected” and “Undetected” quantities on the task details page.

Start efficiently obtaining tg US data immediately

Standardized export formats are the foundation of data-driven marketing. The KK-DATA platform provides a complete pipeline from number generation, cross-platform screening to flexible export, supports multi-platform screening such as Telegram, WhatsApp, Line, Zalo, etc., and supports batch export of tg US data (CSV/TXT, UTF-8/GBK optional). Whether you are importing CRM, EDM or private messaging tools, you can find the matching configuration.

👉Log in to the console to start screening numbers Two-way contact customer service https://t.me/kkdata_robot For more technical details, please refer to Official Documents or visit Official Home Page