POST /v3/audience → audienceCreate

Overview

Property Value
REST endpoint POST /v3/audience
GraphQL operation audienceCreate
Input type AudienceCreateInput
Output type AudienceCreatePayload (data: Audience, errors: [AudienceCreateMutationError!])

Multi-step operations

POST /v3/audience creates a legacy data-group audience (included/excluded data group IDs). The GraphQL equivalent is audienceCreate, which uses an Audience Predictor workflow—not a 1:1 mirror of the REST body.

REST-only behavior GraphQL target
AudienceName, IncludedDataGroupIds, ExcludedDataGroupIds No direct inputs on AudienceCreateInput; use audienceStrategy instead
AdvertiserId (top-level string) parentId.advertiserId (also supports parentId.adGroupId)
GeoForCounts on create Read field on returned Audience, not part of create input

Variables must include required parentId and audienceStrategy. See AudienceStrategyInput for strategy-specific fields.

Input field mapping

Input type: AudienceCreateInput

REST field GraphQL field GraphQL type Required Notes
AdvertiserId parentId.advertiserId ID Required REST top-level advertiser ID maps to nested parentId.advertiserId; GraphQL also supports parentId.adGroupId.
AudienceName N/A N/A Required audienceCreate uses Audience Predictor strategy inputs; no direct audienceName field on AudienceCreateInput.
Description N/A N/A Optional Not currently available in GraphQL
IncludedDataGroupIds N/A N/A Required Legacy data-group intersection model; not mirrored on AudienceCreateInput.
ExcludedDataGroupIds N/A N/A Optional Legacy data-group exclusion model; not on AudienceCreateInput.
GeoForCounts N/A N/A Optional geoForCounts is a read field on Audience, not part of AudienceCreateInput.

GraphQL-only input fields (no REST equivalent)

GraphQL field GraphQL type Description
audienceStrategy AudienceStrategyInput! Required by audienceCreate; discriminated union—set exactly one strategy. No REST counterpart on POST /v3/audience.
parentId ParentIdInput! Required parent union; partially populated from REST AdvertiserId via parentId.advertiserId.

Output field mapping

Output type: Audience (returned as data on AudienceCreatePayload)

REST response field GraphQL field GraphQL type Nullable Notes
AdvertiserId advertiser.id ID! Not nullable GraphQL returns nested Advertiser reference rather than flat advertiserId string.
AudienceId id ID! Not nullable N/A
AudienceName name String! Not nullable Renamed on Audience; not settable via AudienceCreateInput for legacy data-group create.
Description description String Nullable N/A
IncludedDataGroupIds N/A N/A N/A GraphQL exposes targetingDataGroups connection, not a flat included ID list.
ExcludedDataGroupIds N/A N/A N/A No flat excluded data-group ID list on Audience.
LastUpdatedAtUTC lastUpdatedAt DateTime! Not nullable REST LastUpdatedAtUTC → lastUpdatedAt.
IsAutoGenerated isAutoGenerated Boolean! Not nullable N/A
GeoForCounts geoForCounts String Nullable N/A
UniqueUserCount activeUniques.idsCount Long Nullable GraphQL nests counts under activeUniques.
WebCount activeUniques.idsWebCount Long Nullable REST WebCount → activeUniques.idsWebCount.
InAppCount activeUniques.idsInAppCount Long Nullable REST InAppCount → activeUniques.idsInAppCount.
CtvCount activeUniques.idsConnectedTvCount Long Nullable REST CtvCount → activeUniques.idsConnectedTvCount.
PersonsCount activeUniques.personsCount Long Nullable REST PersonsCount → activeUniques.personsCount.
HouseholdCount activeUniques.householdCount Long Nullable REST HouseholdCount → activeUniques.householdCount.
ActiveIDsCountExpanded activeIDsCountExpanded Boolean Nullable N/A
SuccessfullyRetrievedCounts successfullyRetrievedCounts Boolean Nullable N/A

Endpoint-specific nested types and enums

ParentIdInput

Discriminated union on AudienceCreateInput.parentId. Set exactly one parent field.

GraphQL field GraphQL type Required Notes
advertiserId ID Optional Maps from REST AdvertiserId. Set exactly one of advertiserId or adGroupId.
adGroupId ID Optional GraphQL-only parent; no REST counterpart on POST /v3/audience. Set exactly one of advertiserId or adGroupId.

AudienceStrategyInput

Discriminated union on AudienceCreateInput.audienceStrategy. Set exactly one strategy field.

GraphQL field GraphQL type Required Notes
audiencePredictor AudiencePredictorAudienceInput Optional Audience Predictor workflow (GraphQL create path); sole strategy field on AudienceStrategyInput—must be set when audienceStrategy is provided.

AudiencePredictorAudienceInput

Nested under audienceStrategy.audiencePredictor. Set exactly one modeling-source field.

GraphQL field GraphQL type Required Notes
default Boolean Optional When true, models from the campaign seed audience (simplest create path). Set exactly one of default, seed, advertiserImportedData, crm, ipAddressCookieMatching, or universalPixel.
seed AudiencePredictorSeedInput Optional Model from an existing seed audience (seedId required). Set exactly one of default, seed, advertiserImportedData, crm, ipAddressCookieMatching, or universalPixel.
advertiserImportedData AudiencePredictorAdvertiserImportedDataInput Optional Model from advertiser-imported data (targetingDataIds required). Set exactly one of default, seed, advertiserImportedData, crm, ipAddressCookieMatching, or universalPixel.
crm AudiencePredictorCrmInput Optional Model from CRM data (targetingDataIds required). Set exactly one of default, seed, advertiserImportedData, crm, ipAddressCookieMatching, or universalPixel.
ipAddressCookieMatching AudiencePredictorIpAddressCookieMatchingDataInput Optional Model from IP cookie-matching data (targetingDataIds required). Set exactly one of default, seed, advertiserImportedData, crm, ipAddressCookieMatching, or universalPixel.
universalPixel AudiencePredictorUniversalPixelInput Optional Model from universal-pixel visitors (targetingDataIds required). Set exactly one of default, seed, advertiserImportedData, crm, ipAddressCookieMatching, or universalPixel.

AudiencePredictorSeedInput

GraphQL field GraphQL type Required Notes
seedId ID! Required Seed audience ID.
minimumValueScore Int Optional Minimum value score for inclusion.

AudiencePredictorAdvertiserImportedDataInput / AudiencePredictorCrmInput / AudiencePredictorIpAddressCookieMatchingDataInput / AudiencePredictorUniversalPixelInput

Each modeling-source input exposes the same shape:

GraphQL field GraphQL type Required Notes
targetingDataIds [ID!]! Required Targeting data IDs for the chosen modeling source.

Code examples

REST example

POST /v3/audience HTTP/1.1
Content-Type: application/json
TTD-Auth: AUTH_TOKEN_PLACEHOLDER

{
  "AdvertiserId": "adv123",
  "AudienceName": "Sports Fans",
  "IncludedDataGroupIds": ["dg1", "dg2"]
}

GraphQL example

POST /graphql HTTP/1.1
Content-Type: application/json
TTD-Auth: AUTH_TOKEN_PLACEHOLDER

mutation CreateAudience($input: AudienceCreateInput!) {
  audienceCreate(input: $input) {
    data {
      id
      name
      description
      lastUpdatedAt
      advertiser {
        id
      }
      activeUniques {
        idsCount
        idsWebCount
      }
    }
    errors {
      ... on UserError {
        message
        field
      }
    }
  }
}

Variables:

{
  "input": {
    "parentId": {
      "advertiserId": "adv123"
    },
    "audienceStrategy": {
      "audiencePredictor": {
        "default": true
      }
    }
  }
}

REST data-group fields (AudienceName, IncludedDataGroupIds, etc.) are not direct inputs on AudienceCreateInput. For other modeling sources, set a different field on audiencePredictor (see AudiencePredictorAudienceInput above).