openapi: "3.0.4" info: title: "TTD Data API" version: "v0.1" description: | Python SDK for The Trade Desk Data API. Provides operations for ingesting advertiser data, third-party data, and offline conversions, as well as handling data subject deletion and opt-out requests. For more information, see the official API documentation: - [Advertiser targeting data (1PD)](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-advertiser-firstparty) - [Third-party targeting data (3PD)](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-thirdparty) - [Offline conversions (CAPI)](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-providerapi-offlineconversion) Deletions and opt-outs: - [Advertiser](https://open.thetradedesk.com/advertiser/docsApp/GuidesAdvertiser/data/doc/post-data-deletion-optout-advertiser) - [Third party](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/audience/doc/post-data-deletion-optout-thirdparty) - [Merchant](https://open.thetradedesk.com/provider/docsApp/GuidesProvider/retail/doc/post-data-deletion-optout-merchant) paths: /data/advertiser: post: tags: - "Advertiser" summary: "Upload first-party data for the specified ID for use in audience targeting." operationId: "IngestAdvertiserData" parameters: - name: "TTD-Auth" in: "header" description: "Data API token for authentication." required: true schema: type: "string" requestBody: content: application/json: schema: $ref: "#/components/schemas/AdvertiserDataRequest" required: true responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/AdvertiserDataServerResponse" "400": description: "Bad Request - Invalid JSON, missing items, advertiser not configured, or policy restrictions" content: application/json: schema: $ref: "#/components/schemas/AdvertiserDataServerResponse" "403": description: "Forbidden - Cannot create new targeting data for this advertiser" content: application/json: schema: type: "string" "413": description: "Request Entity Too Large - Request size exceeds the allowed limit" content: application/json: schema: type: "string" "429": description: "Too Many Requests - Rate limit exceeded" content: application/json: schema: $ref: "#/components/schemas/AdvertiserDataServerResponse" "500": description: "Internal Server Error - Unexpected server error" "503": description: "Service Unavailable - Handler disabled or request dropped" servers: - url: "https://usw-data.adsrvr.org" /data/thirdparty: post: tags: - "ThirdParty" summary: "Upload third-party data for the specified data provider for use in audience targeting." operationId: "IngestThirdPartyData" parameters: - name: "TTD-Auth" in: "header" description: "Data API token for authentication." required: true schema: type: "string" requestBody: content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDataRequest" required: true responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDataServerResponse" "400": description: "Bad Request - Invalid JSON, missing items, data provider not configured, or policy restrictions" content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDataServerResponse" "403": description: "Forbidden - Cannot create new targeting data for this data provider" content: application/json: schema: type: "string" "413": description: "Request Entity Too Large - Request size exceeds the allowed limit" content: application/json: schema: type: "string" "429": description: "Too Many Requests - Rate limit exceeded" content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDataServerResponse" "500": description: "Internal Server Error - Unexpected server error" "503": description: "Service Unavailable - Handler disabled or request dropped" servers: - url: "https://bulk-data.adsrvr.org" /providerapi/offlineconversion: post: tags: - "OfflineConversion" summary: "Upload offline conversion data for the specified data provider." operationId: "IngestOfflineConversionData" parameters: - name: "TTD-Auth" in: "header" description: "Data API token for authentication." required: true schema: type: "string" requestBody: content: application/json: schema: $ref: "#/components/schemas/OfflineConversionDataRequest" required: true responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/OfflineConversionDataServerResponse" "400": description: "Bad Request - Invalid JSON, missing items, data provider not configured, or policy restrictions" content: application/json: schema: $ref: "#/components/schemas/OfflineConversionDataServerResponse" "403": description: "Forbidden - Cannot create offline conversion data for this data provider" content: application/json: schema: type: "string" "413": description: "Request Entity Too Large - Request size exceeds the allowed limit" content: application/json: schema: type: "string" "429": description: "Too Many Requests - Rate limit exceeded" content: application/json: schema: $ref: "#/components/schemas/OfflineConversionDataServerResponse" "500": description: "Internal Server Error - Unexpected server error" "503": description: "Service Unavailable - Handler disabled or request dropped" servers: - url: "https://offlineattrib.adsrvr.org" /data/deletion-optout/advertiser: post: tags: - "DeletionOptOut" summary: "Delete IDs shared with The Trade Desk for the specified advertiser ID." operationId: "DataSubjectRequestAdvertiserData" parameters: - name: "TTD-Auth" in: "header" description: "Data API token for authentication." required: true schema: type: "string" requestBody: content: application/json: schema: $ref: "#/components/schemas/AdvertiserDsrRequest" required: true responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/AdvertiserDsrResponse" "400": description: "Bad Request - Invalid JSON, missing items, advertiser not configured, or policy restrictions" content: application/json: schema: $ref: "#/components/schemas/AdvertiserDsrResponse" "403": description: "Forbidden - Cannot process data subject request for this advertiser" content: application/json: schema: type: "string" "413": description: "Request Entity Too Large - Request size exceeds the allowed limit" content: application/json: schema: type: "string" "429": description: "Too Many Requests - Rate limit exceeded" content: application/json: schema: $ref: "#/components/schemas/AdvertiserDsrResponse" "500": description: "Internal Server Error - Unexpected server error" "503": description: "Service Unavailable - Handler disabled or request dropped" servers: - url: "https://usw-data.adsrvr.org" /data/deletion-optout/merchant: post: tags: - "DeletionOptOut" summary: "Delete IDs shared with The Trade Desk via a product catalog for the specified merchant ID." operationId: "DataSubjectRequestMerchantData" parameters: - name: "TTD-Auth" in: "header" description: "Data API token for authentication." required: true schema: type: "string" requestBody: content: application/json: schema: $ref: "#/components/schemas/MerchantDsrRequest" required: true responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/MerchantDsrResponse" "400": description: "Bad Request - Invalid JSON, missing items, merchant not configured, or policy restrictions" content: application/json: schema: $ref: "#/components/schemas/MerchantDsrResponse" "403": description: "Forbidden - Cannot process data subject request for this merchant" content: application/json: schema: type: "string" "413": description: "Request Entity Too Large - Request size exceeds the allowed limit" content: application/json: schema: type: "string" "429": description: "Too Many Requests - Rate limit exceeded" content: application/json: schema: $ref: "#/components/schemas/MerchantDsrResponse" "500": description: "Internal Server Error - Unexpected server error" "503": description: "Service Unavailable - Handler disabled or request dropped" servers: - url: "https://usw-data.adsrvr.org" /data/deletion-optout/thirdparty: post: tags: - "DeletionOptOut" summary: "Delete IDs shared with The Trade Desk for the specified data provider ID." operationId: "DataSubjectRequestThirdPartyData" parameters: - name: "TTD-Auth" in: "header" description: "Data API token for authentication." required: true schema: type: "string" requestBody: content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDsrRequest" required: true responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDsrResponse" "400": description: "Bad Request - Invalid JSON, missing items, data provider not configured, or policy restrictions" content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDsrResponse" "403": description: "Forbidden - Cannot process data subject request for this data provider" content: application/json: schema: type: "string" "413": description: "Request Entity Too Large - Request size exceeds the allowed limit" content: application/json: schema: type: "string" "429": description: "Too Many Requests - Rate limit exceeded" content: application/json: schema: $ref: "#/components/schemas/ThirdPartyDsrResponse" "500": description: "Internal Server Error - Unexpected server error" "503": description: "Service Unavailable - Handler disabled or request dropped" servers: - url: "https://usw-data.adsrvr.org" components: schemas: AdvertiserData: required: - "Name" type: "object" properties: Name: type: "string" TimestampUtc: type: "string" format: "date-time" nullable: true TtlInMinutes: type: "integer" format: "int32" nullable: true BaseBidCPM: type: "number" format: "double" nullable: true BaseBidCPMMetadata: type: "string" nullable: true BidFactor: type: "number" format: "double" nullable: true additionalProperties: false AdvertiserDataItem: required: - "Data" type: "object" properties: TDID: type: "string" nullable: true DAID: type: "string" nullable: true UID2: type: "string" nullable: true UID2Token: type: "string" nullable: true RampID: type: "string" nullable: true CoreID: type: "string" nullable: true EUID: type: "string" nullable: true EUIDToken: type: "string" nullable: true ID5: type: "string" nullable: true NetID: type: "string" nullable: true FirstID: type: "string" nullable: true MerkuryID: type: "string" nullable: true IqviaPPID: type: "string" nullable: true Data: type: "array" items: $ref: "#/components/schemas/AdvertiserData" CookieMappingPartnerId: type: "string" nullable: true additionalProperties: false x-speakeasy-name-override: BaseAdvertiserDataItem AdvertiserDataRequest: required: - "AdvertiserId" type: "object" properties: AdvertiserId: type: "string" DataProviderId: type: "string" nullable: true Items: type: "array" items: $ref: "#/components/schemas/AdvertiserDataItem" nullable: true DataLoadTraceId: type: "string" nullable: true DataOrigins: type: array items: $ref: "#/components/schemas/DataOrigin" nullable: true additionalProperties: false AdvertiserDataResponseErrorCode: enum: - "Unknown" - "BaseBidCPMMetadataTooLong" - "MissingUserId" - "UserNotMapped" - "Deprecated_MissingCookieMappingPartnerId" - "InvalidBidFactor" - "DataNameTooLong" - "InvalidTtlInMinutes" - "InvalidBaseBidCPM" - "Uid2Error" type: "string" AdvertiserDataServerResponse: type: "object" properties: FailedLines: type: "array" items: $ref: "#/components/schemas/AdvertiserDataServerResponseLine" nullable: true additionalProperties: false AdvertiserDataServerResponseLine: type: "object" properties: TDID: type: "string" format: "uuid" nullable: true DataName: type: "string" nullable: true ErrorCode: $ref: "#/components/schemas/AdvertiserDataResponseErrorCode" Message: type: "string" nullable: true ItemNumber: type: "string" nullable: true additionalProperties: false AdvertiserDsrFailedLine: type: "object" properties: AdvertiserId: type: "string" nullable: true DataProviderId: type: "string" nullable: true TDID: type: "string" format: "uuid" nullable: true ErrorCode: $ref: "#/components/schemas/DsrErrorCode" Message: type: "string" nullable: true ItemNumber: type: "string" nullable: true additionalProperties: false AdvertiserDsrRequest: type: "object" properties: AdvertiserId: type: "string" nullable: true DataProviderId: type: "string" nullable: true Items: type: "array" items: $ref: "#/components/schemas/PartnerDsrDataItem" nullable: true DataLoadTraceId: type: "string" nullable: true RequestType: $ref: "#/components/schemas/PartnerDsrRequestType" additionalProperties: false AdvertiserDsrResponse: type: "object" properties: FailedLines: type: "array" items: $ref: "#/components/schemas/AdvertiserDsrFailedLine" nullable: true additionalProperties: false DsrErrorCode: enum: - "Unknown" - "InvalidUserId" - "Uid2Error" type: "string" MerchantDsrFailedLine: type: "object" properties: MerchantId: type: "string" nullable: true TDID: type: "string" format: "uuid" nullable: true ErrorCode: $ref: "#/components/schemas/DsrErrorCode" Message: type: "string" nullable: true ItemNumber: type: "string" nullable: true additionalProperties: false MerchantDsrRequest: type: "object" properties: MerchantId: type: "integer" format: "int64" nullable: true Items: type: "array" items: $ref: "#/components/schemas/PartnerDsrDataItem" nullable: true DataLoadTraceId: type: "string" nullable: true RequestType: $ref: "#/components/schemas/PartnerDsrRequestType" additionalProperties: false MerchantDsrResponse: type: "object" properties: FailedLines: type: "array" items: $ref: "#/components/schemas/MerchantDsrFailedLine" nullable: true additionalProperties: false OfflineConversionDataItem: required: - "TimestampUtc" - "TrackingTagId" type: "object" properties: TDID: type: "string" nullable: true DAID: type: "string" nullable: true UID2: type: "string" nullable: true UID2Token: type: "string" nullable: true RampID: type: "string" nullable: true EUID: type: "string" nullable: true EUIDToken: type: "string" nullable: true DataProviderUserId: type: "string" nullable: true UserIdArray: type: "array" items: maxItems: 2 minItems: 2 type: "array" items: type: "string" description: "Array of [type, id] pairs." nullable: true CookieMappingPartnerId: type: "string" nullable: true OrderId: type: "string" nullable: true ImpressionId: type: "string" nullable: true TrackingTagId: type: "string" TimestampUtc: type: "string" format: "date-time" Value: type: "string" nullable: true ValueCurrency: type: "string" nullable: true Country: type: "string" nullable: true Region: type: "string" nullable: true Metro: type: "string" nullable: true City: type: "string" nullable: true MerchantId: type: "string" nullable: true EventName: type: "string" nullable: true LineItems: type: "array" items: $ref: "#/components/schemas/RealTimeConversionEventLineItem" nullable: true PrivacySettings: type: "array" items: $ref: "#/components/schemas/RealTimeConversionEventsPrivacySetting" nullable: true TD1: type: "string" nullable: true TD2: type: "string" nullable: true TD3: type: "string" nullable: true TD4: type: "string" nullable: true TD5: type: "string" nullable: true TD6: type: "string" nullable: true TD7: type: "string" nullable: true TD8: type: "string" nullable: true TD9: type: "string" nullable: true TD10: type: "string" nullable: true additionalProperties: false x-speakeasy-name-override: BaseOfflineConversionDataItem OfflineConversionDataRequest: required: - "DataProviderId" type: "object" properties: DataProviderId: type: "string" UserIdArrayMetadataFormat: type: "array" items: type: "string" nullable: true Items: type: "array" items: $ref: "#/components/schemas/OfflineConversionDataItem" nullable: true DataLoadTraceId: type: "string" nullable: true DataOrigins: type: array items: $ref: "#/components/schemas/DataOrigin" nullable: true additionalProperties: false OfflineConversionDataResponseErrorCode: enum: - "Unknown" - "MissingOrInvalidTDIDAndImpressionId" - "MissingOrInvalidTrackingTagId" - "InvalidMerchantId" - "ChinaPII" - "InvalidTimestamp" - "InvalidUserIdTypeOrUserId" - "Unauthorized" - "Uid2Error" type: "string" OfflineConversionDataServerResponse: type: "object" properties: FailedLines: type: "array" items: $ref: "#/components/schemas/OfflineConversionDataServerResponseLine" nullable: true additionalProperties: false OfflineConversionDataServerResponseLine: type: "object" properties: OrderId: type: "string" nullable: true ImpressionId: type: "string" nullable: true TDID: type: "string" nullable: true TrackingTagId: type: "string" nullable: true TimestampUtc: type: "string" format: "date-time" ErrorCode: $ref: "#/components/schemas/OfflineConversionDataResponseErrorCode" Message: type: "string" nullable: true ItemNumber: type: "string" nullable: true OriginalRequest: $ref: "#/components/schemas/OfflineConversionDataItem" additionalProperties: false PartnerDsrDataItem: type: "object" properties: TDID: type: "string" nullable: true DAID: type: "string" nullable: true UID2: type: "string" nullable: true UID2Token: type: "string" nullable: true RampID: type: "string" nullable: true CoreID: type: "string" nullable: true EUID: type: "string" nullable: true EUIDToken: type: "string" nullable: true ID5: type: "string" nullable: true NetID: type: "string" nullable: true FirstID: type: "string" nullable: true MerkuryID: type: "string" nullable: true IqviaPPID: type: "string" nullable: true additionalProperties: false x-speakeasy-name-override: BasePartnerDsrDataItem PartnerDsrRequestType: enum: - "OptOut" - "Deletion" type: "string" RealTimeConversionEventLineItem: type: "object" properties: item_code: type: "string" nullable: true name: type: "string" nullable: true qty: type: "string" nullable: true price: type: "string" nullable: true cat: type: "string" nullable: true additionalProperties: false RealTimeConversionEventsPrivacySetting: type: "object" properties: privacy_type: type: "string" nullable: true is_applicable: type: "string" nullable: true consent_string: type: "string" nullable: true additionalProperties: false StringStringValueTuple: type: "object" properties: Item1: type: "string" nullable: true Item2: type: "string" nullable: true additionalProperties: false ThirdPartyData: required: - "Name" type: "object" properties: Name: type: "string" TimestampUtc: type: "string" format: "date-time" nullable: true TtlInMinutes: type: "integer" format: "int32" nullable: true additionalProperties: false ThirdPartyDataItem: required: - "Data" type: "object" properties: DataProviderUserId: type: "string" nullable: true TDID: type: "string" nullable: true DAID: type: "string" nullable: true UID2: type: "string" nullable: true UID2Token: type: "string" nullable: true RampID: type: "string" nullable: true CoreID: type: "string" nullable: true EUID: type: "string" nullable: true EUIDToken: type: "string" nullable: true ID5: type: "string" nullable: true NetID: type: "string" nullable: true FirstID: type: "string" nullable: true MerkuryID: type: "string" nullable: true IqviaPPID: type: "string" nullable: true Data: type: "array" items: $ref: "#/components/schemas/ThirdPartyData" CookieMappingPartnerId: type: "string" nullable: true additionalProperties: false x-speakeasy-name-override: BaseThirdPartyDataItem ThirdPartyDataRequest: required: - "DataProviderId" type: "object" properties: DataProviderId: type: "string" Items: type: "array" items: $ref: "#/components/schemas/ThirdPartyDataItem" nullable: true DataLoadTraceId: type: "string" nullable: true IsUserIdAlreadyHashed: type: "boolean" default: false DataOrigins: type: array items: $ref: "#/components/schemas/DataOrigin" nullable: true additionalProperties: false ThirdPartyDataResponseErrorCode: enum: - "Unknown" - "MissingUserId" - "UserNotMapped" - "DataNameTooLong" - "UnauthorisedThirdPartyDataWithBaseBidCPM" - "InvalidTtlInMinutes" - "Uid2Error" type: "string" ThirdPartyDataServerResponse: type: "object" properties: FailedLines: type: "array" items: $ref: "#/components/schemas/ThirdPartyDataServerResponseLine" nullable: true additionalProperties: false ThirdPartyDataServerResponseLine: type: "object" properties: DataProviderUserId: type: "string" nullable: true TDID: type: "string" format: "uuid" nullable: true DataName: type: "string" nullable: true ErrorCode: $ref: "#/components/schemas/ThirdPartyDataResponseErrorCode" Message: type: "string" nullable: true ItemNumber: type: "string" nullable: true additionalProperties: false ThirdPartyDsrFailedLine: type: "object" properties: DataProviderId: type: "string" nullable: true TDID: type: "string" format: "uuid" nullable: true ErrorCode: $ref: "#/components/schemas/DsrErrorCode" Message: type: "string" nullable: true ItemNumber: type: "string" nullable: true additionalProperties: false ThirdPartyDsrRequest: type: "object" properties: DataProviderId: type: "string" nullable: true BrandId: type: "string" nullable: true Items: type: "array" items: $ref: "#/components/schemas/PartnerDsrDataItem" nullable: true DataLoadTraceId: type: "string" nullable: true RequestType: $ref: "#/components/schemas/PartnerDsrRequestType" additionalProperties: false ThirdPartyDsrResponse: type: "object" properties: FailedLines: type: "array" items: $ref: "#/components/schemas/ThirdPartyDsrFailedLine" nullable: true additionalProperties: false DataOriginType: type: string enum: - "Advertiser" - "DataProvider" - "Integration" - "Onboarder" DataOrigin: required: - "Id" - "Type" type: object properties: Id: type: string Type: $ref: "#/components/schemas/DataOriginType" additionalProperties: false