This article details the parameter specifications for the NewsBreak Conversions API, categorized by parameter family. It outlines the core event data, user match keys, and parameters required for different use cases to build a reliable server-to-server integration for ad attribution and delivery optimization.
Basic server parameters
| Parameter | Format | Description | Hash required | Required | Notes and example |
|---|---|---|---|---|---|
| callback | string | The click ID parameter for tracking (e.g., from nbclid). | No | Required | Pass the exact value received from the click URL without modification. Example: 12345abcde |
| nb_value | string | The conversion value associated with the event. | No | Required | Use a decimal number. Do not include currency symbols or commas. Example: 19.99 |
| tracking_id | string | A unique ID for your account, already provided for you in the request code snippet on Ad Manager | No | Required | Example: tracking_id=1231231234 |
| utm_source | string | The marketing channel of this request | No | Required | Example: Meta, Tiktok, Google etc. |
| event_type | string | The type of conversion event. | No | Required | Example: complete_payment |
| cta_time | Long | A Unix timestamp in seconds indicating when the actual event occurred. | No | Required | A 10-digit Unix timestamp in seconds for when the event happened (not when send to NewsBreak). Do not use milliseconds. Example: 1699991234 |
| event_id | string | A unique identifier for the event, used for deduplication. | No | Required | Any unique string, could be used for dedup and tracking trouble shooting. Recommended to use a UUID (App) or order ID (e-commerce). Example: evt_54321_abc |
| event_source_url | string | The browser URL where the event happened. | No | Required | The full URL including the protocol (http/https). Example: [link removed] |
No matter if you're an E-commerce, App or lead gen advertiser, to improve the performance of your ads, please send back as many Customer and device parameters as you can.
Customer and device information parameters
| Parameter | Format | Description | Hash required | Required | Notes and example |
|---|---|---|---|---|---|
| string | Yes | At least one of email, phone, external_id is required | Remove leading/trailing spaces and convert to lowercase. Example: Input: John_Smith@gmail.com Normalized: john_smith@gmail.com SHA256: 62a14e44f765419d10fea99367361a727c12365e2520f32218d505ed9aa0f62f | ||
| phone | string | Phone | Yes | At least one of email, phone, external_id is required | Strip symbols, letters, and leading zeros. A country code is required for all phone numbers, even for single-country datasets (e.g., '1' for the US). Example: Input: (650)123-4567 Normalized: 16501234567 SHA256: 1f41a6876308cc581e7c096db4b342524d51f06f1df35537e30859e3956b5e89 |
| external_id | string | External ID | Yes | At least one of email, phone, external_id is required | A unique advertiser ID (e.g., loyalty ID, user ID, or external cookie ID). Multiple IDs can be sent per event. Ensure formatting matches IDs sent through other channels. |
| tp_gaid | string | Google Advertising ID for Android devices. | No | Required for Android device | The raw GAID string. Use lowercase with hyphens. Example: 38400000-8cf0-11bd-b23e-10b96e40000d |
| tp_idfa | string | Apple Identifier for Advertisers for iOS devices. | No | Required for iOS device | The raw IDFA string. Use uppercase with hyphens. Example: EA7583CD-A667-48BC-B806-42ECB2B48606 |
| tp_ip | string | Client IP Address | No | Required | A valid IPv4 or IPv6 browser address (IPv6 preferred). Do not hash this parameter or include spaces. Provide the actual IP for accurate reporting. (Manually configured for server events). Examples: IPv4: 168.210.321.234 IPv6: 2001:db8:4f3a:82e1:c915:68fa:2b4e:7109 |
| tp_ua | string | Client User Agent | No | Required | The browser user agent associated with the event (required for website events). Sending this alongside the IP address improves matching and ad delivery. (Manually configured for server events). Examples: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/87.0.4280.141 |
| tp_connection_type | string | How the device is connected to internet | No | Requried | Example: Wifi 4G LTE |
| tp_isp | string | Internet service provider | No | Recommended | Example: Comcast AT&T Verizon |
| tp_browser_lang | string | Browser language | No | Required | Example: en es |
| fn | string | First Name | Yes | Recommended | Prefer lowercase Roman alphabet characters (a-z) without punctuation. Special characters require UTF-8 encoding. Examples: Input: Mary -> Normalized: mary SHA256: 6915771be1c5aa0c886870b6951b03d7eafc121fea0e80a5ea83beb7c449f4ec |
| ln | string | Last Name | Yes | Recommended | Prefer lowercase Roman alphabet characters (a-z) without punctuation. Special characters require UTF-8 encoding. |
| db | string | Date of Birth | Yes | Recommended | Use the YYYYMMDD format for dates, allowing various month, day, and year combinations (punctuation optional). Year: YYYY (1900 to current). Month: MM (01-12). Day: DD (01-31). Example: Input: 2/20/1998 -> Normalized: 19980220 SHA256: 01ae64b08cec912dd538b9b8384ad9aef095100c1868b61fec8cdb736de71409 |
| gender | string | Gender | Yes | Recommended | Provide gender as a single lowercase initial. Example: 'f' for female 'm' for male |
| tp_city | string | City | Yes | Recommended | Prefer lowercase Roman characters (a-z) without punctuation, spaces, or special characters. Encode special characters in UTF-8. Examples: paris london newyork |
| tp_state | string | State | Yes | Recommended | Provide the 2-character ANSI abbreviation in lowercase. For non-U.S. states, use lowercase without punctuation, spaces, or special characters. Examples: az ca |
| zip | string | Zip Code | Yes | Recommended | Format in lowercase without spaces or dashes. For U.S. zip codes, include only the first 5 digits. Example: 94035 |
| tp_country | string | Country | Yes | Recommended | Provide the 2-letter ISO 3166-1 alpha-2 country code in lowercase. Always include the country code to improve global matching rates, even for single-country lists. Example: Input: United States -> Normalized: us SHA256: 79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621 |
| tp_os | string | The operating system of the device. | No | Recommended | Standard OS names. Usually lowercase or specific capitalization. Example: iOS Android |
| tp_osv | string | The version of the operating system. | No | Recommended | The exact version string. Example: 14.4.2 11.0 |
| tp_bundle_id | string | The app bundle identifier (iOS) or package name (Android). | No | Recommended | The exact reverse-DNS format bundle ID. Example: com.company.appname |
| tp_idfv | string | Identifier for vendor iOS | No | Recommended | Example 68753A44-4D6F-1226-9C60-0050E4C00067 |
| tp_device_model | string | The specific hardware model of the device. | No | Recommended | The exact device model string from the OS. Example: iPhone12,1 SM-G991U |
| timezone | string | The timezone of the device. | No | Recommended | Use standard tz database format (Area/Location) or abbreviations. Example: America/Los_Angeles UTC |
| tp_carrier | string | The mobile network carrier of the device. | No | Recommended | The exact carrier name string. Example: Verizon AT&T |
| screen width | string | The width of the device screen in pixels. | No | Recommended | A whole number representing pixels. Example: 1080 |
| screen height | string | The height of the device screen in pixels. | No | Recommended | A whole number representing pixels. Example: 1920 |
| screen density | string | The pixel density or scale factor of the screen. | No | Recommended | A decimal number representing the scale (e.g., 2.0 for @2x, 3.0 for @3x). Example: 2.5 |
E-commerce data parameters
| Parameter | Format | Description | Hash required | Required | Notes and example |
|---|---|---|---|---|---|
| order_id | string | Unique identifier for the transaction/order. | No | Required for complete_payment | Use the exact order ID from your system. No spaces. Example: ORD-987654321 |
| predicted_ltv | number | The predicted lifetime value of the customer. | No | Recommended | A decimal number representing the value. Do not include currency symbols. Example: 1250.50 |
| product_infos | object | An array of objects containing detailed information about the products. | No | Required | A JSON array of objects, each containing product details like id, quantity, price. Example: [{"id": "sku123", "quantity": 2, "price": 19.99}] |
| -> currency | string | The currency used for the transaction. | No | Required | Use the 3-letter ISO 4217 currency code in uppercase. Example: USD |
| -> total_quantity | string | The total number of items in the transaction. | No | Required | A whole number representing the total quantity. Example: 3 |
| -> item_count | string | The number of distinct items/products in the transaction. | No | Required | A whole number representing the count of unique items. Example: 2 |
| -> item_list | array | A list of item IDs or SKUs. | No | Required | A JSON array of strings representing the item identifiers. Example: ["sku123", "sku456"] |
| --> item_group_id | string | The item group id for an item | No | Required | The exact SKU string used in your catalog. Example: A12345 |
| --> sku_id | string | The specific SKU identifier for an item. | No | Required | The exact SKU string used in your catalog. Example: TSHIRT-BLU-M |
| --> product_category | string | The category of the product. | No | Required | A string representing the product category taxonomy. Example: Apparel > Shirts > T-Shirts |
| --> price | string | The total price or value of the event. | No | Required | A decimal number. Do not include currency symbols or commas. Example: 49.99 |
| --> sale_price | string | The discounted or sale price of the item. | No | Required | A decimal number. Do not include currency symbols. Example: 39.99 |
| --> quantity | string | The quantity of a specific item. | No | Required | A whole number. Example: 1 |
| --> item_total | string | The total price for a specific item line (price * quantity). | No | Required | A decimal number. Do not include currency symbols. Example: 79.98 |
| --> link | string | URL of the product | No | Required | Example: https://findbest.com/products/hooded-knit-sweate |
| --> image_link | string | URL of the product image creative | No | Required | Example: https://findbest.myshopify.com/cdn/shop/files/hooded-knit-sweate.jpg |
| --> video_link | string | URL of the product video creative | No | Required | Example: https://findbest.com/cdn/shop/videos/84117914.mp4 |
App data parameters
| Parameter | Format | Description | Hash required | Required | Notes and example |
|---|---|---|---|---|---|
| mmp_id | String | ID of the Mobile Measurement Partner | No | Required | Example: appsflyer |
| is_attributed | Boolean | Whether the conversion is attributed | No | Required | Example: TRUE |
| cta_time | Long | Click time (Unix timestamp) | No | Required | Example: 1627890123 |
| is_vta | Boolean | View-through attribution flag | No | No | Example: FALSE |
| vta_time | Long | Impression time (Unix timestamp) | No | No | Example: 1627890123 |
| is_reattributed | Boolean | Re-attribution flag | No | No | Example: FALSE |
| reattributed_at | Long | Time of re-attribution | No | No | Example: 1627890123 |
| reattribute_window | string | Re-attribution window size | No | No | Example: 30 |
| is_rejected | Boolean | Rejection flag | No | No | Example: FALSE |
| blocked_reason | String | Reason for rejection/blocking | No | No | Example: fraud |
| blocked_reason_value | String | Blocked reason code | No | No | Example: 101 |
| blocked_sub_reason | String | Sub-reason for blocking | No | No | Example: click_spam |
Lead gen parameters
| Parameter | Format | Description | Hash required | Required | Notes and example |
|---|---|---|---|---|---|
| lead_id | string | Lead ID of your prodcut or service | No | Required | Example: 1234abc |
| product_description | string | Description of the product or service of the lead | No | Required | Example: Portable cooler |