iSpot.tv
Upload conversion data to iSpot.tv for TV ad measurement and attribution. Zeotap syncs your first-party conversion events directly to the iSpot.tv Conversions API as gzip-compressed CSV uploads, enabling closed-loop TV campaign measurement.
Prerequisites
- An iSpot.tv account with Conversions API access
- iSpot.tv Client ID and Client Secret (provided by your iSpot.tv Customer Success representative)
- One or more conversion site IDs (format:
TC-####-#) — iSpot Customer Success issues these when the CSV format is approved
Authentication
iSpot.tv uses OAuth 2.0 client credentials authentication.
- Contact your iSpot.tv Customer Success representative to obtain your Client ID and Client Secret
- In Zeotap, select iSpot.tv as your destination
- Enter your Client ID and Client Secret
Zeotap exchanges these credentials for a bearer token at sync time. iSpot.tv tokens are valid for 24 hours and Zeotap requests a fresh token on every sync run.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| API Environment | Select | Yes | API environment. Default: Production (https://api.ispot.tv/v4) |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Insert | Yes |
| Upsert | — |
| Update | — |
| Mirror | — |
iSpot.tv’s Conversions API is append-only. Each sync run uploads new conversion events. Events cannot be updated or deleted after upload — the iSpot platform deduplicates based on datetime + siteid + client identifiers.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | — |
| Remove | — |
| Mirror | — |
| Upsert | — |
iSpot.tv does not expose an audience or list-management API. Use sync modes to upload conversion events only.
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
datetime | UTC timestamp of the conversion event (ISO 8601 or YYYY-MM-DD HH:MM:SS) |
siteid | iSpot conversion site ID for the event (format: TC-####-#). Provided by iSpot Customer Success |
Default Destination Fields
The iSpot.tv Conversions CSV format accepts the following columns. Zeotap writes them in this exact order on every upload.
| Field | Type | Description |
|---|---|---|
ip | string | Client IP address (e.g., 66.87.152.32) |
useragent | string | Client user agent string |
datetime | string | UTC datetime of the event (required) |
siteid | string | Conversion site ID, format TC-####-# (required) |
app | string | Allowed values: web or app |
type | string | Event type — e.g., visit, checkout, store_locator |
customdata | string | Free-form custom event or segmentation data |
Any column not mapped is emitted as an empty string in the uploaded CSV.
How It Works
- Authentication: Zeotap exchanges your Client ID and Client Secret for an OAuth 2.0 bearer token at
POST /v4/oauth2/token. - CSV assembly: For each batch, Zeotap builds a CSV with the fixed column order above, then gzip-compresses the file in memory.
- Upload: The gzipped CSV is uploaded as
multipart/form-datatoPOST /v4/metrics/conversionswith the form field nameupload[file]. - Batching: Rows are chunked into groups of 50,000 per upload. This keeps the compressed payload well under iSpot.tv’s 200 MB per-file limit for typical row sizes.
- Retry handling: Transient failures (5xx, 429) are retried automatically with exponential backoff (up to 3 retries).
Rate Limits
- iSpot.tv enforces rate limits on
/metrics/*endpoints. Uploading a conversion file counts as a single request regardless of the number of rows in the file, so most syncs stay well within limits. - If you experience HTTP 429 responses, Zeotap backs off and retries automatically. Persistent 429s usually indicate too many concurrent syncs against the same account — stagger sync schedules.
Best Practices
- Use ISO 8601 UTC timestamps for
datetimeto avoid time-zone ambiguity - Always populate
siteid— iSpot drops rows without a valid site ID silently - Set
apptoweborapp(notmobile,desktop, etc.) — other values are rejected - Keep
customdatavalues short and consistent — iSpot uses this field for segmentation reports - Schedule syncs after conversion windows close (24–48 hours post-exposure) to capture late-attributed events
Troubleshooting
Authentication failed: invalid client credentials
Verify your Client ID and Client Secret with your iSpot.tv Customer Success representative. Credentials can be rotated via iSpot support — update them in Zeotap under the destination settings after rotation.
HTTP 400: invalid CSV format
iSpot.tv rejects files whose columns do not exactly match ip,useragent,datetime,siteid,app,type,customdata. Zeotap always emits this exact header, so 400s from the upload endpoint usually indicate bad row data — most commonly a malformed datetime value or an app value other than web/app. Check the first failed batch’s rows against the format guide.
Rows missing from iSpot reports
- Verify
datetimevalues are in UTC and within iSpot’s attribution window - Confirm
siteidvalues are active (iSpot silently drops unknown or deactivated site IDs) - Allow up to 24 hours for uploaded conversions to appear in reports — iSpot processes uploaded files asynchronously
Upload returning HTTP 401 after some time
OAuth tokens are valid for 24 hours. If a single sync run exceeds that window, the token expires mid-run. Split very long syncs into multiple smaller scheduled runs.
HTTP 413 / file too large
The 50,000-row chunk size is tuned so the gzipped payload stays under 200 MB for typical row sizes. If your rows contain very large customdata values, lower the effective chunk by splitting the source model into smaller batches upstream.
Conversion type not appearing in measurement reports
iSpot.tv requires the type column value to match one of the event types configured for your conversion site. Unknown type values are accepted but not mapped to measurement reports. Contact iSpot Customer Success to register new event types before syncing.