Skip to navigation

Resolve named identifiers to the best-matching program

The flat REST path: one JSON object of named identifier parameters in, a diagnostic envelope out. Each additional identifier parameter you provide increases the precision of the results: bundle alone fully resolves single-channel apps but returns a structured miss on aggregator apps; adding channelId or channelName resolves the channel and joins the schedule at the lookup instant; adding title resolves the program directly. One uniform response shape covers every outcome — parts are populated or empty, never reshaped.

Unlike the passthrough route, this route returns confidence and per-candidate diagnostics in the body — use it for impression-log enrichment, DSP-side lookups, and integration debugging. Both routes honor a supplied instant; this one reads it from the flat timestamp field below. Pass verbose: true during integration against an environment that offers the debug object: it shows exactly how each input was read. The sandbox at dev-epg-api.pixalate.com offers it.

Authentication

x-api-keystring

Your Pixalate-provided API key, in the request header on every route. Credentials are never accepted in query parameters. An API key may be obtained by signing up for an account on the Pixalate developer website.

OR
AuthorizationBasic

Username/password alternative to the API-key header. Headers only — credentials are never accepted in query parameters.

Request

This endpoint expects an object.
bundlestringRequired

Required. App store bundle/ID. Alone it fully resolves single-channel apps; on an aggregator (multi-channel) app with no channel or show identifier alongside it, the result is a structured CHANNEL_UNRESOLVED miss, never a guess.

channelIdstringOptional

Native/platform channel identifier, matched exactly against known identifiers (substring containment as a fallback). Strictly supersedes channelName — when present, the name is not consulted.

channelNamestringOptional

Channel display name (fuzzy name match). Consulted only when channelId is absent. Capped at 256 characters; longer values are truncated.

titlestringOptional

Show/program title. Fuzzy match, scoped to the declared app’s catalog; a resolved show always carries its channel association. When the channel path and the show path disagree, the channel + timestamp result wins and this input is marked CONFLICT in verbose debug. Capped at 256 characters; longer values are truncated.

osenumOptional

Platform/OS, from a fixed enumerated vocabulary. An out-of-vocabulary value, including a different letter case, → 400 — never silently degraded. Omit the field for a platform not listed; resolution then runs against all platforms.

devicetypeintegerOptional

Optional OpenRTB device type. Accepted and retained for forward compatibility; not consulted by resolution during the beta.

timestampdatetimeOptional

ISO 8601 UTC lookup instant; absent means now. Per item in batch, so an impression log enriches against the schedule as of each impression. Up to 5 minutes in the future clamps to now (TIMESTAMP_CLAMPED notice); further in the future, older than the 7-day window, or unparseable → 400.

verbosebooleanOptionalDefaults to false

Ask for the debug object in the response. Whether the request is answered with one is a property of the environment: an environment that does not offer the debug object returns the ordinary envelope without it, and with nothing on the wire to say so. The sandbox at dev-epg-api.pixalate.com offers it.

Response

Lookup performed (hit or structured miss).

noticeslist of enums
Allowed values:
candidateslist of objects

The best match on a hit; empty on a miss.

reasonenumOptional

Present when candidates is empty or degraded. Single-valued — the earliest resolution stage that failed; a stage that never ran doesn’t count. Finer-grained internal subcategories are never serialized in any response.

ValueMeaningWhat to do
APP_UNRESOLVEDThe bundle did not resolve to a supported app.Confirm the bundle is a CTV app in scope.
OUT_OF_SCOPEThe app resolved and is not an EPG app — enrichment does not apply to it (e.g. a game).Nothing — enrichment is not applicable.
NO_COVERAGEThe app resolved and is an EPG app, but the EPG data needed to answer is not held — no lineup for it, or no schedule covering the instant.Treat the impression as unenriched. Not billable.
CHANNEL_UNRESOLVEDChannel-bearing inputs produced no channel on this app — including an app-only request on an aggregator app.Check the identifier is correct and belongs to the declared app; pass a channel id or name on aggregator traffic.
SHOW_UNRESOLVEDThe show input produced no content on this app.Check the title; pass a channel identifier alongside it.
Allowed values:
debugobjectOptional

Present on the parameterized lookup route when verbose=true and the environment offers the debug object. It is an integration aid the sandbox at dev-epg-api.pixalate.com offers, not a guarantee of every environment: an environment that does not offer it answers a verbose request with the ordinary envelope and no debug object, and with no notice, reason code, or error to say so. Identifier-level disclosures (supersession, ignored-empty, unsupported, conflicts) live here and only here. Use it during integration: it shows exactly how each input was read.

errorobjectOptional

Batch only — populated in a slot whose item was invalid (echoes what the single-request 400 would have said).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
413
Content Too Large Error
429
Too Many Requests Error
503
Service Unavailable Error