{ "opencollection": "1.0.0", "info": { "name": "VideoAmp Public Audiences API", "version": "2026-07-31" }, "request": { "auth": { "type": "oauth2", "flow": "authorization_code", "authorizationUrl": "https://login.videoamp.com/authorize", "accessTokenUrl": "https://login.videoamp.com/oauth/token", "credentials": { "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}" } } }, "items": [ { "info": { "name": "audiences", "type": "folder" }, "items": [ { "info": { "name": "List Audiences", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences", "params": [ { "name": "audienceIds", "value": "", "type": "query", "description": "Query param audience_ids returns only matching audiences for given valid audience legacy ids. The values in this field must be valid numeric ids." }, { "name": "audienceUuids", "value": "", "type": "query", "description": "Query param audience_uuids returns only matching audiences for given valid audience uuids. The values in this field must be valid UUIDs." }, { "name": "cadences", "value": "", "type": "query", "description": "Query param cadences returns only the audiences with refresh cadence in the provided list. Accepted Values: - `one_time` - `weekly` - `monthly` - `quarterly`" }, { "name": "currencyOfRecord", "value": "", "type": "query", "description": "Query param 'currencyOfRecord' refers to the data and methodologies used for VideoAmp currency guarantees within a given broadcast year. If not provided, 'demo' audiences default to VideoAmp's latest currency of record. 'advance' audiences from all currency of record will be returned." }, { "name": "filteredAgencyAdvertiserIds", "value": "", "type": "query", "description": "Query param filteredAgencyAdvertiserIds returns only the audiences these agency advertisers have access to." }, { "name": "filteredAgencyIds", "value": "", "type": "query", "description": "Query param filteredAgencyIds returns only the audiences these agencies have access to." }, { "name": "level", "value": "", "type": "query", "description": "Query param 'level' filters the audiences by level. This filter only applies to demographic audiences (i.e. 'type=demo') as advanced audiences are all household level. If unset, the default is to return all audiences. - LEVEL_UNSPECIFIED: Unspecified level - HOUSEHOLD: Household based audience - PERSON: Person based audience" }, { "name": "orderBy", "value": "", "type": "query", "description": "Query param 'orderBy' specifies the order of the results. This field is case sensitive. Accepted Values: - 'desc(createdAt)' - (Default) - 'asc(createdAt)' - 'desc(name)' - 'asc(name)'" }, { "name": "pageSize", "value": "", "type": "query", "description": "Query param pageSize specifies the number of results to include in a page of results." }, { "name": "pageToken", "value": "", "type": "query", "description": "Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests." }, { "name": "query", "value": "", "type": "query", "description": "Query param 'query' filters the audiences by name, description, id or uuid. This field is case insensitive." }, { "name": "status", "value": "", "type": "query", "description": "Query param 'status' filters the audiences by status. This field is case insensitive. Accepted Values: - 'ready' - Ready to use - 'failed' - Failed to create Audience - 'processing' - Audience is being created - 'draft' - Audience to be created" }, { "name": "type", "value": "", "type": "query", "description": "Query param 'type' filters the audiences by type. Accepted Values: - 'advanced' - Returns the combination of 'owned' and 'shared' audiences - 'demo' - Returns VideoAmp's global demographic audiences - 'shared' - Returns audiences that are shared to this organization - 'owned' - Returns only audiences that are created within this organization - 'exposure' - Returns exposure audiences - 'content' - Returns content audiences - 'user_provided' - Returns user provided audiences - 'composite' - Returns composite audiences If no type filter is specified, all audiences will be returned." }, { "name": "useCases", "value": "", "type": "query", "description": "Query param useCases filters the audiences by use cases. If multiple use cases are provided, the result will contain audiences with at least one of the provided use cases. This field is case insensitive. Accepted Values: - `measurement` - Returns audiences that can be used for ad measurement - `activation` - Returns audiences that can be used for activation - `content` - Returns audiences that can be used for content measurement" }, { "name": "year", "value": "", "type": "query", "description": "Query param 'year' filters the audiences by broadcast year. This filter retrieves demographic audiences with metrics for the given broadcast year. Accepted Values: - '2020' - '2099'" } ] }, "docs": "This endpoint returns a list of the audiences accessible to the user. The list can be filtered and sorted. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages)." }, { "info": { "name": "Create Audience", "type": "http" }, "http": { "method": "POST", "url": "https://api.videoamp.dev/v1/audiences", "params": [ { "name": "validateOnly", "value": "", "type": "query", "description": "This field validates the required fields and the requesting user's permissions. An audience resource will not be created when this field is set to true. This field is optional and defaults to `false`. (default true)" } ], "body": { "type": "json", "data": "{}" } }, "docs": "This endpoint triggers the create audience process. To use the creation endpoint, the current holding company must be onboarded, please contact Videoamp support for more information. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages)." }, { "info": { "name": "List Statuses", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences/status", "params": [ { "name": "orderBy", "value": "", "type": "query", "description": "Query param 'orderBy' specifies the order of the results. This field is case sensitive. Accepted Values: - 'desc(createdAt)' - (Default) - 'asc(createdAt)' - 'desc(name)' - 'asc(name)'" }, { "name": "pageSize", "value": "", "type": "query", "description": "Query param pageSize specifies the number of results to include in a page of results." }, { "name": "pageToken", "value": "", "type": "query", "description": "Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests." }, { "name": "requestId", "value": "", "type": "query", "description": "Query param requestIds filters the audiences by request id. This field is synonymous with the Audience's UUID." }, { "name": "status", "value": "", "type": "query", "description": "Query param 'status' filters the audiences by status. This field is case insensitive. Accepted Values: - 'ready' - Ready to use - 'failed' - Failed to create Audience - 'processing' - Audience is being created - 'draft' - Audience to be created" } ] }, "docs": "This endpoint returns a list of audience creation statuses. The list can be filtered and sorted. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages)." }, { "info": { "name": "List Exports", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences/:audienceId/exports", "params": [ { "name": "audienceId", "value": "", "type": "path", "description": "Audience identifier whose exports to list. **Accepted formats** (all map to the same audience resource): - UUID (string) — **use this**. Matches 'audience.audienceUUId' (v1) or 'audience.id' (v2). - Legacy integer (string-encoded) — backwards compatibility only. Matches 'audience.audienceId' (v1) or 'audience.legacy_id' (v2). Use UUID for new integrations. - '-' (single dash) — wildcard. Returns exports across all audiences accessible to the calling organization. Use to enumerate exports without first knowing the audience id. An unknown audience id returns '200' with an empty 'results' array (not '404'). Malformed values that are neither UUID, integer, nor '-' return '400' with a 'field_violations' entry." }, { "name": "pageSize", "value": "", "type": "query", "description": "Query param pageSize specifies the number of results to include in a page of results. Defaults to `20` when omitted. Maximum allowed value is `3000` — values above this return `400` with a `page_size` field violation. Pair with `pageToken` to iterate through large result sets." }, { "name": "pageToken", "value": "", "type": "query", "description": "Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests." }, { "name": "sorts", "value": "", "type": "query", "description": "Sort order for the result list. Specify each sort key as with **no space** between them — e.g., `-created_at`. Whitespace is stripped before parsing, so `+ created_at` and `+created_at` are treated identically. **Field names are case sensitive.** Default when omitted: `-created_at` (newest first). **Sortable fields:** - `created_at` — when the export was created - `audience_id` — audience integer id - `export_type` — destination type (`CUSTOM_S3`, `LIVERAMP`, etc.) - `status` — execution status **Direction prefixes:** - `+` ascending (also the default if no prefix is supplied) - `-` descending **Multiple keys:** repeat the query parameter to compose ordering, e.g. `?sorts=-status&sorts=+created_at`. Keys are applied in the order received. **Note:** unlike v2 endpoints (which use `orderBy=created_at desc` syntax), this endpoint uses prefix notation. Do not mix the two." } ] }, "docs": "Returns the paginated list of exports configured for the given audience.\n\n**Why**: Discover all delivery destinations and runs for an audience. Use this endpoint to monitor recurring export pipelines, audit which destinations have received the audience, and confirm whether a previous export reached `READY` before triggering downstream activation.\n\n**When**: Call after `POST /v1/audiences/{audienceId}/exports` to poll the per-export `status` until it reaches a terminal state (`READY` or `FAILED`)" }, { "info": { "name": "Create Export", "type": "http" }, "http": { "method": "POST", "url": "https://api.videoamp.dev/v1/audiences/:audienceId/exports", "params": [ { "name": "audienceId", "value": "", "type": "path", "description": "Audience identifier the export will be created against. **Accepted formats** (all map to the same audience resource): - UUID (string) — **use this**. Matches 'audience.audienceUUId' (v1) or 'audience.id' (v2). - Legacy integer (string-encoded) — backwards compatibility only. Matches 'audience.audienceId' (v1) or 'audience.legacy_id' (v2). Use UUID for new integrations. Returns '404' if the audience does not exist or is not accessible to the calling organization." }, { "name": "validateOnly", "value": "", "type": "query", "description": "This field validates the required fields and the requesting user's permissions. An export resource will not be created when this field is set to true. This field is optional and defaults to `false`. (default true)" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new export of the audience to a downstream destination.\n\n**Why**: Push audience members to a destination. Each export is owned by the calling organization and runs on a one-time or recurring cadence.\n\n**When**: Returns `201` with the created `Export` (`status=QUEUED`). The audience may be in any status — the export materializes once its data is available. Check `audience_export_get` to monitor progress until `status` reaches `READY` or `FAILED`.\n\n**Discovering valid export types**: Not" }, { "info": { "name": "Get Export", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences/:audienceId/exports/:id", "params": [ { "name": "audienceId", "value": "", "type": "path", "description": "Audience identifier of the export to retrieve. **Accepted formats**: - UUID (string) — **use this**. Matches 'audience.audienceUUId' (v1) or 'audience.id' (v2). - Legacy integer (string-encoded) — backwards compatibility only. Matches 'audience.audienceId' (v1) or 'audience.legacy_id' (v2). Use UUID for new integrations. - '-' (single dash) — wildcard for \"any audience in the calling organization\". Useful when the export 'id' is known but the audience is not. The server enforces calling-organization scope regardless of which form you use. When a concrete identifier is supplied, it must reference the same audience that owns the export 'id'; mismatch returns '404'." }, { "name": "id", "value": "", "type": "path", "description": "The export's unique identifier (UUID). Obtain from the response of 'audience_export_create' (the 'id' field) or from a previous 'audience_export_list' page. The supplied 'id' must belong to the audience referenced by 'audienceId'. If the export exists but its audience differs, the endpoint returns '404' (the relationship is enforced server-side). Malformed values return '400'." } ] }, "docs": "Returns the full details of a single export, identified by its UUID and audience.\n\n**Why**: Retrieve the current state of one export — its execution `status`, the destination-specific spec object, and any per-destination metadata populated once the run reaches `READY`.\n\n**When**: This is the canonical endpoint for **checking export status**. After `audience_export_create` returns the new export's `id`, check this endpoint to monitor progress until `status` is `READY` or `FAILED` (both terminal)." }, { "info": { "name": "Get Audience", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The Audience's UUID or id (int64)." } ] }, "docs": "This endpoint returns the requested audience and it's details. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages)." }, { "info": { "name": "Batch Get Audiences", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences:batchGet", "params": [ { "name": "ids", "value": "", "type": "query", "description": "The UUIDs or legacy integer Ids of the audiences to retrieve. Must be all UUIDs or all legacy integer Ids. A maximum of 100 audiences can be retrieved in a batch." } ] }, "docs": "This endpoint returns the requested audiences and their details. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages)." }, { "info": { "name": "Look Up Id Types", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v1/audiences:lookUpIdTypes" }, "docs": "Returns all identifier types supported for audience ingestion and export within the authenticated organization. Each entry includes the type name, description, and ingestible/exportable flags.\n\n### Why\n\nOrganizations are provisioned with a specific set of ID types based on their data partnerships. This is the authoritative reference for valid types in your org — preventing failures from passing unsupported values to audience creation or export.\n\n### When\n\nCall this endpoint when you need to:\n- P" }, { "info": { "name": "List Audiences", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v2/audiences", "params": [ { "name": "advertiserIds", "value": "", "type": "query", "description": "Filters audiences by permissioned advertiser UUID(s). Includes audiences permissioned directly to the advertiser as well as those permissioned to any ancestor organization. **Org-level inheritance**: Audiences permissioned to a parent org are visible to all child advertisers. Filtering by two advertisers in the same org may return identical results — both inherit the same org-level pool. This is expected behavior, not a bug. **Multi-advertiser queries**: Results are a deduplicated union, not a concatenation. total_size equals the union count — do not sum per-advertiser counts. **Advertiser-exclusive audiences**: To find audiences exclusive to one advertiser, inspect `permissioned_entities` on each result and filter client-side. Values must be valid UUIDs; duplicates are not permitted." }, { "name": "agencyIds", "value": "", "type": "query", "description": "Filters audiences by permissioned agency UUID(s). Returns audiences accessible to the given agency IDs. Includes audiences permissioned directly to the agency as well as those permissioned to any of its ancestor organizations. Values must be valid UUIDs; duplicates are not permitted." }, { "name": "broadcastDate", "value": "", "type": "query", "description": "Selects which broadcast year's metrics to return based on the broadcast year range containing the specified date. Only applies to 'GLOBAL_DEMOGRAPHIC' audiences; ignored for other types. Uses ISO-8601 date format ('YYYY-MM-DD'). If omitted, the most recent metrics for the given 'currencyOfRecord' are returned. If the date falls outside the available range for the currency of record, a 400 error is returned with the valid date range." }, { "name": "cadences", "value": "", "type": "query", "description": "Filters audiences by their refresh cadence — how frequently the audience membership is recalculated. Use to find audiences with specific refresh patterns for scheduling-sensitive workflows. Accepts multiple values (OR logic); case-insensitive. Available values: ONE_TIME, `WEEKLY`, `MONTHLY`, `QUARTERLY`." }, { "name": "classifications", "value": "", "type": "query", "description": "Filters audiences by their __classification__. Case-insensitive. Accepts multiple values (OR logic). Available values: - EXPOSURE - `CONTENT` - `CUSTOM_DEMOGRAPHIC` - `USER_PROVIDED` - `GLOBAL_DEMOGRAPHIC` - `COMPOSITE` - `MODELED` **Note on `GLOBAL_DEMOGRAPHIC` and `use_cases`:** `GLOBAL_DEMOGRAPHIC` audiences vary in their supported `use_cases`. Not all `GLOBAL_DEMOGRAPHIC` audiences support `AD_MEASUREMENT` — some only support `CONTENT_MEASUREMENT`. Combining `classifications=GLOBAL_DEMOGRAPHIC` with `useCases=AD_MEASUREMENT` returns only the subset that supports ad measurement. Omit the `useCases` filter to retrieve all `GLOBAL_DEMOGRAPHIC` audiences regardless of supported use cases." }, { "name": "createdByName", "value": "", "type": "query", "description": "Case-insensitive substring filter on the 'created_by_name' field of the audience. Useful for finding audiences created by a specific user or team. Matches any audience whose creator's display name contains the supplied string. Combine with 'ownership=OWNED' to narrow results to audiences created by your organization." }, { "name": "currencyOfRecord", "value": "", "type": "query", "description": "Filters audiences by their currency of record, which identifies the measurement panel and the data and methodologies used for VideoAmp currency guarantees within a given broadcast year. For 'GLOBAL_DEMOGRAPHIC' audiences, combine with 'broadcastDate' to select the correct metrics. Provide as a numeric string (int64 encoded as string). Invalid or unavailable values return a 400 error listing valid options." }, { "name": "description", "value": "", "type": "query", "description": "Case-insensitive substring filter on the audience 'description' field. Matches any audience whose description contains the supplied string. Useful for finding audiences annotated with specific campaign or workflow context. Combine with 'name' or 'classifications' for more precise filtering. Empty string or omitting this parameter returns all audiences regardless of description. Use the 'search' parameter instead for broader matching across multiple fields." }, { "name": "excludeClassifications", "value": "", "type": "query", "description": "Query param excludeClassifications will exclude audiences that have the specified __classification__. This field is case insensitive. The available options and restrictions for this field are the same as the __classifications__ filter. For example, to retrieve all audiences except `GLOBAL_DEMOGRAPHIC` audiences: `excludeClassifications=GLOBAL_DEMOGRAPHIC`." }, { "name": "ids", "value": "", "type": "query", "description": "Filters to a specific set of audiences by their UUID id values. Use when you already know which audiences you need — e.g., to batch-fetch metadata for a saved list of audience IDs. Values must be valid UUIDs. Combine with `statuses=READY` to verify all listed audiences are usable." }, { "name": "legacyIds", "value": "", "type": "query", "description": "Filters to a specific set of audiences by their legacy numeric legacy_id values. Use when integrating with systems that store legacy integer IDs rather than UUIDs. Prefer `ids` (UUID) for new integrations; use `legacy_ids` only when working with older systems or data stores that reference the numeric ID." }, { "name": "level", "value": "", "type": "query", "description": "Filters audiences by measurement granularity. 'HOUSEHOLD': household-level metrics (default for most classifications). 'PERSON': person-level metrics for 'GLOBAL_DEMOGRAPHIC' audiences. Omit to return all levels. Unsupported combinations return empty metrics fields. - LEVEL_UNSPECIFIED: Default filter value; returns all audiences regardless of level. Do not use in requests — omit instead. - HOUSEHOLD: Household-level reach and frequency metrics. The default for most classifications. - PERSON: Person-level demographic metrics. Available only for GLOBAL_DEMOGRAPHIC audiences." }, { "name": "name", "value": "", "type": "query", "description": "Case-insensitive substring filter on the audience 'name' field. Matches any audience whose name contains the supplied string. Use this to narrow results when browsing audiences for a specific campaign. Combine with 'statuses' or 'classifications' to further refine results. Empty string or omitting this parameter returns all audiences regardless of name. Use the 'search' parameter instead for broader matching across multiple fields." }, { "name": "orderBy", "value": "", "type": "query", "description": "Controls the sort order of returned audiences. Specify a comma-separated list of field_name direction pairs. Direction is optional; omit for ascending order, use 'desc' for descending. Defaults to 'created_at desc' (most recently created first) when omitted. Sortable fields: 'created_at', 'created_by_name', 'name', 'currency_of_record', 'legacy_id'. Example: 'currency_of_record, name desc' sorts by currency of record ascending, then name descending." }, { "name": "ownership", "value": "", "type": "query", "description": "Filters by audience ownership relative to the calling organization. 'OWNED': audiences created by your organization. 'SHARED': audiences another organization has granted you access to via the Resource Sharing API — use when collaborating cross-org on measurement or activation campaigns. 'SYSTEM': VideoAmp-provided audiences such as GLOBAL_DEMOGRAPHIC audiences. Omit to return all three ownership types. Only one value is accepted per request." }, { "name": "pageSize", "value": "", "type": "query", "description": "Query param pageSize specifies the number of results to include in a page of results. Defaults to a server-determined page size when omitted. Use larger values (100-500) for batch processing or data export workflows; use smaller values for interactive UI displays with progressive loading. Pair with `pageToken` to paginate through large result sets. Must be a positive integer; excessively large values may increase response latency." }, { "name": "pageToken", "value": "", "type": "query", "description": "Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests." }, { "name": "search", "value": "", "type": "query", "description": "Filters audiences by matching the provided string against name, description, id, or uuid (case-insensitive). Returns audiences where any of these fields contain the given value. Use this parameter for broad searches when the exact field is unknown or does not matter. For more precise filtering, use the 'name' or 'description' query parameters instead." }, { "name": "statuses", "value": "", "type": "query", "description": "Filters audiences by processing status. Use READY to find audiences eligible for immediate use in measurement workflows. Exports can be created against an audience in any status. `PROCESSING` and `QUEUED` indicate the audience is being built and is not yet usable. `FAILED` indicates processing encountered an error. Accepts multiple values (OR logic); case-insensitive. Available values: `QUEUED`, `PROCESSING`, `READY`, `FAILED`." }, { "name": "useCases", "value": "", "type": "query", "description": "Filters audiences to those supporting at least one of the specified use cases. The use_cases property on an audience determines which downstream operations are available — e.g., only audiences with `AD_MEASUREMENT` can be used in ad measurement campaigns. Case-insensitive; accepts multiple values (OR logic). Available values: `ACTIVATION`, `AD_MEASUREMENT`, `CONTENT_MEASUREMENT`." } ] }, "docs": "Returns a paginated, filterable list of audiences accessible to the calling organization. The caller's organization context controls visibility; the `use_cases` field on each audience determines eligible downstream operations.\n\n**Why**: Discover and enumerate audiences before passing them to downstream workflows. Use this endpoint to find READY audiences by classification, ownership, use case, or name before creating measurements or exports. Use GET /v2/audiences/{id} when the audience UUID is a" }, { "info": { "name": "Create Audience", "type": "http" }, "http": { "method": "POST", "url": "https://api.videoamp.dev/v2/audiences", "params": [ { "name": "validateOnly", "value": "", "type": "query", "description": "When true, validates the request body (required fields, enum values, permissions) without creating the audience. Use to pre-flight a create request before committing — especially useful when building audience creation UI or automating bulk audience creation workflows where early error detection reduces wasted processing. Defaults to `false`. A successful validate-only response does not guarantee a subsequent create will succeed if underlying data changes between calls. (default true)" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new audience resource and queues it for processing. Returns the created Audience object with `status=QUEUED`. **Status lifecycle**: `QUEUED` → `PROCESSING` → `READY` (success) or `FAILED` (error). `READY` and `FAILED` are terminal; `QUEUED` and `PROCESSING` are non-terminal. Processing typically takes 10–20 minutes for common audience types; large or complex audiences (e.g., `COMPOSITE`, `USER_PROVIDED` with high identity-match volume) may take longer. Do not treat `PROCESSING` as a te" }, { "info": { "name": "Lookup Demographic Filter Fields", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v2/audiences/lookupDemographicFilterFields", "params": [ { "name": "pageSize", "value": "", "type": "query", "description": "Query param pageSize specifies the number of results to include in a page of results. Defaults to a server-determined page size when omitted. Use larger values (50-100) when building field selectors that display a complete list; use smaller values for progressive-loading UI components. Must be a positive integer. Pair with `pageToken` to paginate through the full catalog. Excessively large values may increase response latency." }, { "name": "pageToken", "value": "", "type": "query", "description": "Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests." }, { "name": "search", "value": "", "type": "query", "description": "Optional keyword filter to narrow the list of demographic filter fields. Performs a case-insensitive substring match against the 'field' identifier (e.g., AGE_RANGE), the 'description' text, and the 'label' display name (e.g., Age Range). Use when you know part of the field name, description, or display label to quickly locate a specific demographic attribute. Omit to retrieve all available fields. Combine with 'pageSize' for efficient browsing of large field catalogs." } ] }, "docs": "Returns a paginated list of demographic filter fields available for building Custom Demographic audiences. Each entry contains the field identifier (`field`), a human-readable label, and a detailed description of the demographic attribute.\n\n**Why**: Useful for two scenarios: populating UI field selectors (e.g., dropdowns in an audience builder) where the available fields are not known ahead of time, and validating or exploring available field identifiers before writing code that references them." }, { "info": { "name": "Lookup Demographic Filter Values", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v2/audiences/lookupDemographicFilterValues", "params": [ { "name": "field", "value": "", "type": "query", "description": "The demographic filter field identifier to look up values for. Must be a valid field identifier returned by GET /v2/audiences/lookupDemographicFilterFields — e.g., 'AGE_RANGE', 'GENDER', 'INCOME'. Values are UPPERCASE with underscore separators. Case-sensitive: use the exact string returned by the fields endpoint. Returns 400 if the field identifier is not recognized for the calling organization." }, { "name": "pageSize", "value": "", "type": "query", "description": "Query param pageSize specifies the number of results to include in a page of results. Defaults to a server-determined page size when omitted. Use larger values (50-100) when building value selectors that display a complete list; use smaller values for progressive-loading UI components. Must be a positive integer. Pair with `pageToken` to paginate through the full value catalog for a field. Excessively large values may increase response latency." }, { "name": "pageToken", "value": "", "type": "query", "description": "Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests." }, { "name": "search", "value": "", "type": "query", "description": "Optional keyword filter to narrow the list of values for the specified field. Performs a case-insensitive substring match against the 'value' identifier (e.g., 13_15) and the 'description' text. Use when you know part of the value string or its description to quickly locate a specific option. Omit to retrieve all available values for the field. Combine with 'pageSize' for efficient browsing of fields with large value catalogs." } ] }, "docs": "Returns a paginated list of valid values for a specific demographic filter field. Each entry contains the value identifier (`value`), a human-readable label, and a description of what the value represents.\n\n**Why**: Before creating a CUSTOM_DEMOGRAPHIC audience, you must know the valid values for each Filter.field you intend to use. This endpoint is the authoritative source for the allowed Filter.values for a given field — do not hardcode value identifiers. The value catalog is field-specific an" }, { "info": { "name": "Get Audience", "type": "http" }, "http": { "method": "GET", "url": "https://api.videoamp.dev/v2/audiences/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The unique identifier for the audience to retrieve. Accepts either a UUID v4 (e.g., 'b21fd4c7-2423-4358-830a-41b3d744e663') or a legacy integer ID encoded as a string (e.g., '\"101010101\"'). UUID is the preferred format for new integrations. Returns 404 if the audience does not exist or is not accessible to the calling organization." } ] }, "docs": "Returns the complete Audience resource for a single known audience ID. Use this endpoint when you already have the audience UUID or legacy integer ID and need to retrieve full details including classification, status, use_cases, owned vs. shared ownership, and the classification-specific definition object (exposure, content, composite, etc.).\n\n**Why**: Retrieve a specific audience directly without filtering through paginated list results. Use to verify audience status before downstream operation" }, { "info": { "name": "Update Audience", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.videoamp.dev/v2/audiences/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The unique identifier of the audience to update. Accepts either a UUID v4 (e.g., 'b21fd4c7-2423-4358-830a-41b3d744e663') or a legacy integer ID encoded as a string (e.g., '\"311637\"'), the same identifier accepted by GetAudience. UUID is the preferred format for new integrations. Supplied as the '{id}' path parameter. Returns 404 if the audience does not exist or is not accessible to the calling organization." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an audience's `name` and/or `description` — the only editable fields. Other attributes (classification, definition, currency of record, use cases, status) are immutable. Provide at least one of `name` or `description`; an empty request returns 400. Returns the full updated Audience.\n\n**Why**: Rename or re-describe an audience without rebuilding it or losing its computed members and metrics. **Example**: a planner renames \"test aud\" to \"Q1 2025 CTV Reach\" before sharing.\n\n**When**: Call t" } ] } ], "bundled": true }