オーディエンス

カスタムオーディエンス

概要

パートナーがCustom Audiencesを作成する方法はいくつかあります。

Audience API (CRM)
Web
Mobile
Flexible

類似オーディエンス（lookalike custom audiences）はターゲティングから除外できません。さらに、同じ広告ラインアイテム（広告グループ）で、カスタムオーディエンスとその類似オーディエンスの両方を同時にターゲティングすることはできません。 オーディエンス管理 オーディエンスは、オーディエンスパートナーおよび Ads API パートナー経由で管理できます。API には、カスタムオーディエンスにアクセスして維持管理するための一連のエンドポイントを提供しています。カスタムオーディエンス情報には、次の2つのエンドポイントを用意しています。

オーディエンスのアップロードと管理の詳細については、Audience API ガイドをご覧ください。 処理時間 一般的に、オーディエンスの変更は6～8時間ごとに実行されるバッチで処理されます。変更の処理中でも、更新対象の既存オーディエンスには影響しません。この期間内に、追加の更新は1回、削除の更新も1回を超えないことを推奨します。 ターゲティング オーディエンスは、過去90日以内に X が所有・運営するクライアント上でアクティブだったユーザーが少なくとも100人に一致する場合にのみターゲティング可能です。GET accounts/:account_id/custom_audiences/:custom_audience_idは、一致ユーザー数が少なすぎてターゲティングできない可能性があるかどうかを示します。 Audience API (CRM)

オーディエンスまたは API パートナーがハッシュ化済み識別子のリストを提供し、X が照合を行って、X 上でのメディアバイイングに利用できるセグメントを生成します。パートナーはこれらのオーディエンスをAudience APIで作成できます。 仕組み

Web MPP のオーディエンスパートナーとの連携時に、X 上でのメディアバイイング向けのターゲティングセグメントを特定するため、標準的なクッキー照合プロセスを提供しています。加えて、広告主はX Web Event Tagを設定してウェブサイトのユーザーデータを収集し、対応する Custom Audience を作成できます。 セットアップ手順

仕組み

Mobile 詳細はCustom Audiences from Mobile Apps に関するブログ投稿をご覧ください。 Flexible Flexible audiencesは、既存のカスタムオーディエンスまたはそのサブセットに基づいてオーディエンスの組み合わせを作成・保存する機能を広告主に提供します。カスタムオーディエンスのメンバーのサブセットは、インタラクションの最近度と頻度に基づいてターゲティングできます。 Custom Audiences の制限付きユースケース 制限事項の詳細はこちら

オーディエンスに関するFAQ

Q: 大量のデータを送信しましたが、オーディエンスのサイズが TOO_SMALL と表示されるのはなぜですか？ A: 現在、データはリアルタイムでオーディエンスに追加されていますが、サイズを算出する処理ジョブは一定時間経過後に実行されます。数時間後には、正しいオーディエンスサイズがUIに表示されるはずです。 Q: オーディエンスのデータ送信を完了し、24時間以上待ちましたが、まだそのオーディエンスをターゲティングできません。次に何をすべきですか？ A: 次の点を確認してください。

渡しているユーザーIDが正しく、形式に問題がないこと。
渡しているオーディエンス名が正しく、過去のメンバーシップ更新と一致していること。
POSTコマンドのレスポンスを確認してください。
ID Syncピクセルが正しく実装されており、ID Syncプロセスの説明どおり、対象サイトに十分なユーザーが訪問してマッピングが行われていることを確認してください。メンバーシップ更新でマッピングされていないユーザーは、ターゲティング対象にはなりません。

他のすべてが正しく機能していることを確認できた場合は、可能な限り詳細な情報とともにXの製品担当者にご連絡ください（望ましい情報の例はGuide to Partner Inboundsを参照）。 Q: エンドポイントは何回呼び出せますか？また、どのようなアルゴリズムで呼び出すべきですか？ A: インクリメンタルな差分で送信し、完全なオーディエンスメンバーシップを再送しないことを強く推奨します。本システムは、世界最大級のウェブサイトに対するインクリメンタルなデータ更新を処理できるスループットでテストされています。オーディエンスの初回アップロードは慎重にスロットリングし、完了までに相当な時間を要する見込みです。 Q: ターゲティングに使用できるオーディエンスの最小サイズは？

オーディエンスの最小サイズは100ユーザー（照合後）です。500ユーザー未満しか照合されないオーディエンスは、X AdsのUIでターゲティングに利用できません。

Q: オーディエンスファイルの処理にはどのくらい時間がかかりますか？また、Xのユーザーインターフェースで利用可能になるまでどのくらいですか？

通常、オーディエンスファイルの処理には4〜6時間かかりますが、ファイルサイズによって異なります。処理が完了すると、X AdsのUIでオーディエンスが利用可能になります。

Q: マッチ率はどのように計算されますか？

マッチ率 = 過去90日間のアクティブなXユーザー数 / 提供したユーザー数

Q: オーディエンスファイルが正しく機能しているかをテストするには？

テスト用のオーディエンスファイルを用意し、広告主ハンドルとして「keltonlynn」を使用できます。これにより、ファイルがXのUIに正しく取り込まれ、ロードできるかを検証できます。

Q: パートナーユーザー識別子（p_user_id）とは何ですか？

貴社が各顧客を一意に識別するために使用する識別子です。

Q: Standard IDとは何ですか？

メールアドレス、デバイスID、Xの@handleまたはIDのいずれかです。

Q: HMACキーはどのように取得しますか？

暗号化されたメールで提供します。公開PGPキーをmpp-inquiry@x.comにご提供ください。すべてが機能していることを確認するため、テストメールをお送りします。検証後、HMACキーを送付します。

Q: 提供されたHMACキーを使ってハッシュ処理が正しく行われたことを検証するには？

Xがテストファイル（サンプルのメールアドレス、デバイスIDなどを含む）と、検証用の結果ハッシュファイルを提供します。これに対して結果を照合できます。

Q: フルデータマッチファイルにサイズ制限はありますか？

いいえ、フルデータマッチファイルにサイズ制限はありません。

Q: フルデータマッチファイルの処理にはどのくらい時間がかかりますか？

Xがファイルを受領してから、処理にはおおよそ1日かかります。

CRM

本ドキュメントでは、カスタムオーディエンスCRMパートナー向けの統合に関する詳細(ファイル形式とデータ交換プロセスを含む)について説明します。概要企業は、顧客に代わって、ハッシュ化された共通ユーザー識別子(メールアドレスなど)またはパートナーユーザーIDのリストをXに提供します。Xはブラインドマッチを実行し、ターゲティング用のXユーザーIDのリストを生成します。ターゲティング用のセグメントは、ads.x.comのキャンペーン設定において、ファイル名で指定された広告主の特定の@ハンドルで利用可能になります。企業からのすべてのファイルは、XがCompanyに付与した専用アカウントを通じて、IronBox(www.golockbox.com)上のセキュアパッケージ経由でXに提供されます。XはIronBoxへのアクセスを提供します。IronBox APIに関するドキュメントはhttps://secure.goironcloud.com/Docs/Help/で確認できます。

パートナーIDマッチング要件

企業がユーザーを追跡するために独自の標準IDシステムを使用している場合(メールアドレス、デバイスID、XユーザーIDなどの一般的なユーザー識別子ではない場合)、以下のプロセスを推奨します。 1. 完全データマッチ まず、企業はXとの共通ユーザー識別子を含むすべてのユーザーレコードの包括的なリストを単一のファイルで提供し、完全データマッチを実行します。これによりパートナーID(p_user_id)からXのID(tw_id)へのマッピングが生成され、Xが保存します。適切な維持管理を確保するため、2〜3ヶ月ごとに定期的に実行されます。マッチが完了すると、Xはこのファイルからのベースラインマッチ率を電子メールで企業に共有します。このファイルの形式は次のとおりです: 命名規則: FullDataMatch.[CompanyName].txt ハッシュアルゴリズム: HMAC_SHA-256 形式: 列1: 共通識別子のHMACハッシュ値列2: パートナーユーザーID(ユーザーごとに一意、ファイル内では重複可) 列区切り文字(CSV): ハッシュ化された共通ユーザー識別子とパートナーIDの区切りにはカンマを使用行区切り値

例: ユーザーレコードAがパートナーユーザーID 1と共通識別子1、2、3を持つ場合:


共通ユーザー識別子 1	p_user_1
共通ユーザー識別子 2	p_user_1
共通ユーザー識別子 3	p_user_1

*共通ユーザー識別子のハッシュ化手順については、以下のセクションを参照してください 2. カスタムセグメントリスト 企業は、X上でのターゲティングのために顧客向けのカスタムオーディエンスを作成するため、p_user_idの形式でユーザーのリストを提供します。

行区切り値
p_user_id
- (上記の1. 完全データマッチセクションで提供されたものと同じです。完全データマッチで提供された値がハッシュ化されている場合、企業はオーディエンスファイルでも同じハッシュ化された値を提供します。提供された値がハッシュ化されていない場合、企業はハッシュ化されていない値を提供します。)

標準のマッチング要件

企業がすべての顧客ユーザー識別子のマッピングに標準のIDを使用していない場合は、以下のプロセスを推奨します。 カスタムセグメントリスト 企業は、顧客に代わってハッシュ化した一般的なユーザー識別子のリストをXに直接提供し、カスタムオーディエンスの作成を依頼します。このファイルの形式は次のとおりです。

行区切りの値
ハッシュ化した一般的なユーザー識別子（例：メールアドレス）
以下に示すファイル命名規則に従う
下記の「ハッシュ化の手順」にあるメールアドレスのハッシュ化手順に従う

カスタムセグメントリストのファイル命名と操作

ファイルの動作はファイル名によって決まり、利用可能な操作および一般的なファイル命名規則は次のとおりです: audiencename_partnername.handle.operation.filetype

audiencename: カスタムオーディエンスの名前。このフィールドは、ads.x.com のキャンペーン設定 UI でオーディエンスを選択する際に表示される名前です（例: brand_loyalty_card_holders）。
partnername: 広告主に代わってデータを提供する企業名（例: company_name）。
handle: カスタムオーディエンスにアクセスできる X アカウント（@handle）（例: @pepsi、@dietpepsi）
operation: new、add、remove、removeall、replace（詳細は下記）
timestamp: 標準の Unix エポック時刻（秒）。アップロードされる各オーディエンスファイルを一意にするために使用します
filetype: ファイルは *.txt 形式である必要があります

オーディエンスの作成と更新

単一のファイルで新しいオーディエンスを作成します（例: loyalty_card_holders_partnername.pepsi.new.txt） Add - リスト内の一致ユーザーを既存のオーディエンスに追加します（例: loyalty_card_holders_partnername.pepsi.add..txt） Remove - 既存のオーディエンスからリスト内の一致ユーザーを削除します（例: loyalty_card_holders_partnername.pepsi.remove..txt） Remove All - 定期更新される累積リストに基づいて、そのクライアントのすべてのオーディエンスから一致ユーザーを削除します（クライアントのオプトアウトリスト）。例: partnername.pepsi.removeall.txt

これは、広告主からオプトアウトしたユーザーの包括的なリストとして使用できます。
X は、このファイルで提供された最新のリストのみを採用し、該当する一致ユーザーについて既存および将来のすべてのオーディエンスに適用します。

このファイルが提供・処理された時点の X ユーザーを対象とします。 Replace - 既存のオーディエンスを削除し、新しいオーディエンスリストに置き換えます。例: loyalty_card_holders_partnername.pepsi.replace..txt 全社オプトアウト - 企業は、企業のオプトアウトポリシーに従ってオプトアウトしたユーザーを削除するための累積オプトアウトファイルを提供します。 X は、この全社オプトアウトファイルで提供された最新のリストのみを採用し、このファイルが提供・処理された時点で一致した X ユーザーについて、既存および将来のすべてのオーディエンスに適用します。全社オプトアウトファイルの形式は次のとおりです。例: partnername.removeall.txt Delete - 現在のオーディエンス一覧から既存のオーディエンスを削除します（例: loyalty_card_holders_partnername.pepsi.delete.txt）

ハッシュ化の手順

X は、一般的なユーザー識別子（例：メールアドレス）をハッシュ化するための、base64 でエンコードされた本番用キーを PGP 経由で安全に共有します。Company は、このキーを base64 デコードして、ハッシュ化に使用する 32 バイトのキーを生成します。 base64 エンコードされたキーの例: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= base64 デコード後のキーの例: /:� TшY 正規化：Company は、ハッシュ化の前に一般的なユーザー識別子に対して基本的な正規化を行います（ただし Device ID を除く。Device ID の正規化セクションを参照してください）。

Eメールの正規化

具体的には、先頭と末尾の空白を削除し、メールアドレスを小文字に変換します。例: 元のメールアドレス: testemail_Organisational_baseball+884@It92I6Ev2B.Com 正規化後: testemail_organisational_baseball+884@it92i6ev2b.com ハッシュ値: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec 注意: エンコードされた HMAC とキーの文字数は、入力やエンコーディングによって変動するため、固定ではありません。

デバイス ID の正規化

デバイス ID のハッシュ化については、SHA-256 ハッシュアルゴリズムと、当社がデータパートナーに提供する共通のソルトを使用するという同一の要件を適用します。メールアドレスの場合と同様にスペースは削除しますが、IDFA/Android ID については小文字への正規化は行いません。IDFA/Android ID は記載のとおりの正確な形式を使用してください。以下は、ハッシュ化前の iOS と Android におけるデバイス ID の生データ形式の例です。 iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 ハッシュ化後の iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b ハッシュ化後の Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

X ユーザーIDの正規化

X の ID は、たとえば @ハンドルのカスタマーリストのようなデータのグループ化が PII ではないものの広告主にとっては非公開であるため、引き続きハッシュ化されます。X ID のハッシュ化には、当社がデータパートナーに提供する共通のソルトと、SHA-256 ハッシュアルゴリズムを使用するという同一の要件が適用されます。X ID および @username の両方からはスペースを削除してください。ただし、User ID の正規化は不要です。@username は正規化のために小文字にしてください。また、@ 記号は username の一部として含めないでください。生の ID の形式は次のとおりです:

User ID: 27674040
@username: testusername

ハッシュ化された User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 ハッシュ化された @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

ID Sync 統合

p_id でデータを送信するパートナーは、広告主またはパートナーのユーザー id と X のユーザー id をマッピングするために、ID Sync プロセスを実施する必要があります。これにより、広告主は X 上で自社のユーザーセグメントを直接ターゲティングできるようになります。パートナーはメンバーシップ更新を送信する際、パラメータ user_identifier_type の値を TALIST_PARTNER_USER_ID または TAWEB_PARTNER_USER_ID に設定する必要があります。

Web のみ: 以下のとおり、広告主のサイトにピクセルを設置して実施できます。
リスト: CRM ページで説明されているいずれかの方法を使用して実施できます。

ピクセル URL


ベース URL
https://analytics.x.com/i/adsct

ピクセルパラメータ


パラメータ	説明
`p_id`	X によって割り当てられたパートナーの id
`p_user_id`	パートナーシステムにおけるユーザーの id

ID同期ピクセル：

パートナーの例としての id が 111、p_user_id の例として abc の場合、生成されるピクセルは次のとおりです：

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

オプトアウトファイルの構成と送信 パートナーは、ターゲティング広告配信のオプトアウトを選択したとパートナーの最善の知見に基づき判断されるユーザーのリストを X に提供する必要があります。ファイルの形式は以下のとおりです。


列番号	列名	列の型	説明
1	Partner ID	string	「partner id」は、各パートナーを一意に識別するために X がパートナーに付与する ID です。
2	パートナーシステムにおけるユーザーの id	string	`p_user_id` は、パートナーがユーザーを識別するために使用する一意の ID です。これらのオプトアウトユーザーを含むファイルは TON upload エンドポイントを使用してアップロードし、アップロードされた data のパスを次の Global Opt Out エンドポイントに送信してください：PUT accounts/:account_id/custom_audiences/global_opt_out。

メンバーシップ更新の送信 エンドポイントのドキュメントで定めているとおり、POST custom_audience_memberships エンドポイントでユーザーを送信する際は、Cookie ベースのマッチングを有効にするために customer ID を渡す必要があります。p_id を用いて data を送信するパートナーは、user_identifier_type を TALIST_PARTNER_USER_ID または TAWEB_PARTNER_USER_ID に設定することが必須です。その他の手順は、Real-Time Audience API Integration Guide に記載されている内容と同様です。

カスタムオーディエンスのユーザーデータ

このドキュメントでは、カスタムオーディエンスのユーザーデータ形式を説明します。 データの正規化 デバイスID:

IDFA - 小文字のダッシュ区切り。例: 4b61639e-47cc-4056-a16a-c8217e029462
AdID - 端末上の元の形式が必要。大文字化せず、ダッシュあり。例: 2f5f5391-3e45-4d02-b645-4575a08f86e
Android id - 端末上の元の形式が必要。大文字化せず、ダッシュやスペースなし。例: af3802a465767e36

メールアドレス:

小文字にし、前後のスペースを削除。例: support@x.com

X ユーザー名:

@ は付けない。小文字にし、前後のスペースを削除。例: jack

X ユーザーID:

標準的な整数。例: 143567

データのハッシュ化 各行のデータは、ソルトなしで SHA256 を使用してハッシュ化する必要があります。さらに、最終的な出力ハッシュは小文字である必要があります。例: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d であり、49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D ではありません。

# Pythonを使用してユーザー@AdsAPIをハッシュ化
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#出力
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

ハッシュ化の追加のコードサンプルは github.com/xdevplatform/ads-platform-tools で確認できます。

カスタムオーディエンス: Web

情報パートナーは広告主に代わり、ターゲティング対象となる ID（p_user_ids）のリストを送信します。これは、p_user_ids と X ユーザー ID の間に対応関係を構築する ID 同期プロセスによって行われます。この対応関係を用いて、ターゲティングに利用できる X ユーザー ID のリストを生成します。これらのカスタムオーディエンスは、ads.x.com の Custom Audiences Web キャンペーン設定でラベルに指定された、広告主固有の @handle に紐づいて利用可能になります。 X は、パートナーのタグやサイトに設置できるセキュアピクセルを提供し、ID（p_user_ids）を X ユーザー ID に照合できるようにします。ID 同期プロセスが完了すると、ターゲティングファイルはパートナーによって作成され、HTTPS エンドポイントを通じて X が取得できるように提供されます。これらのターゲティングファイルは X により定期的に取り込まれ、X の UI で利用可能になります。 X セキュアピクセル X セキュアピクセルは次のとおりです: https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz はパートナーが提供するパートナーのユーザー ID を表します p_id - 123 はパートナー固有の ID（X が付与）を表します パートナーの HTTPS エンドポイントとターゲティングユーザーファイル パートナーは、ターゲティングファイルを定期的に取り込むために使用できる HTTPS エンドポイントと認証情報（ユーザー名/パスワード）を X に提供する必要があります。HTTPS エンドポイントの例は次のとおりです:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - 年のフォーマットコード（YYYY） %M - 月のフォーマットコード（MM） %D - 日のフォーマットコード（DD）送信されるデータは次のファイルで構成されます:

Partner Targeting User File
Targeting Conversion File

すべてのファイルはTSV形式で、各行の各フィールドはタブ文字で区切られます。フィールドの有効な値そのものにタブ文字が含まれることはありません。 許可対象のX IPレンジ: Partner Endpointへのアクセスを許可できるIPレンジは次のとおりです。

199.16.156.0/22
199.59.148.0/22

Partner Targeting User File:

列番号	列名	列タイプ	説明
1	partner id	string	“partner id”は、各パートナーを一意に識別するためにXがパートナーに付与するIDです。
2	advertiser id	string	“advertiser id”は広告主の@handleです。
3	p_user_id	string	“p_user_id”は、パートナーがユーザーを識別するために使用する一意のIDです。
3	confidence score	integer	“confidence score”は任意項目です。推奨レンジは0〜100です。リターゲティング用途の場合、“100”は直接リターゲティングされたユーザーを意味します。0〜99のスコアは、類似ユーザーに対する確信度のレベルを示します。
4	segment label	string	“segment label”は任意項目です。たとえば、製品カテゴリを指定するために“segment label”を使用できます。この“segment label”の使用を推奨します。ads.x.comのUIにおけるCustom Audiencesの人が読める名称に相当するためです。

注記: 新しいPartner Targeting Fileを受領するたびに、特段の合意がない限り、増分ではなく、パートナーがターゲティングを推奨するユーザーの完全なリストであることを前提とします。Partner Targeting Fileの配信頻度は各パートナーと取り決めます。想定どおりにPartner Targeting Fileを受領できない場合は、あらかじめ定義された有効期限付きで前回のバージョンを使用します。

Audience API の連携

概要

Audience API は Ads API のv4の一部としてリリースされ、従来の Audiences エンドポイントに対して複数の改善をもたらします。この新しいエンドポイントは新しい Audience 処理バックエンドを基盤としており、安定性・堅牢性・信頼性の面での強化を実現しています。本ガイドの目的は、Audience API と従来の Audience のアップロードおよび管理プロセスとの違いを明確にすることです。参考ドキュメントはAudience APIのリファレンスページをご確認ください。注意: すべての Audience ユーザーデータはアップロード前に SHA-256 でハッシュ化する必要があります。詳細および受け入れ可能なユーザー識別子の種類やデータ正規化については、user dataページを参照してください。 Audience 機能の変更 v4 時点で以下の Custom Audiences の変更が導入されており、Ads API の v3 がサンセットされた後は非推奨のエンドポイントは利用できなくなります:

非推奨 TON アップロード:
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
非推奨リアルタイム Audiences:
- POST custom_audience_memberships
Custom Audience:
- Custom Audience のすべてのエンドポイントで、リクエストおよびレスポンスから list_type パラメータが削除されます。このパラメータは以前、Audience のユーザー識別子タイプ（例: email、X User ID など）の特定に使用されていましたが、現在は同一の Audience に対して複数のユーザー識別子を受け付けられるようになったため、この値は不要となりました。
一般:
- Audience のルックバック期間は、過去30日から過去90日以内にアクティブなユーザーを対象とするように更新されました
- ターゲット可能となるために必要な一致ユーザーの最小数は、500 ユーザーから 100 ユーザーに引き下げられました

前提条件

Ads API へのアクセス
Audience エンドポイントへのアクセスには、許可リストへの追加が必要です。フォームに記入し、2018-08-01 より前に初回承認されている場合は新しいX Ads Products and Services Agreementに同意してください

Audience のアップロードプロセス以下の表では、旧来と新しい Audience 作成フローの主な違いを示しています。詳細はこの後のセクションで説明します:

プロセスのステップ	Audience API	（非推奨）TON アップロード
シェル Audience の作成	POST custom_audience endpoint で作成可能	POST custom_audience endpoint で作成可能
新規ユーザーの追加	Audience endpoint で `operation_type` の `Update` を使用	POST custom_audience_changes エンドポイントで `operation` の `ADD` を使用
ユーザーの削除	Audience endpoint で `operation_type` の `Delete` を使用	POST custom_audience_changes エンドポイントで `operation` の `REMOVE` を使用
ユーザーのオプトアウト	Audience endpoint と、ユーザーが属する該当の `custom_audience_id` を用いて `operation_type` の `Delete` を使用	Global opt-out endpoint を使用

注意 TON アップロード経路で更新またはオプトアウトされる Audience は、TON Upload エンドポイント経由で対応するリストがアップロードされ、custom_audience_changes エンドポイントを使用して Audience に関連付けられている必要があります。レート制限 Audience API エンドポイントのレート制限はアカウントごとに 1500/1min です。単一のペイロードで送信できるユーザー数に制限はありません。ペイロードの制約は以下のとおりです:

操作の合計数: 2500 operations
最大ペイロードサイズ: 5,000,000 bytes

Audience ユーザー管理新しい Audience を作成するには、以下の手順が必要です

新しいカスタムオーディエンスを作成する

[POST custom_audience]/x-ads-api/audiences エンドポイントを使用して、新しいカスタムオーディエンスの「シェル」を作成し、対応するカスタムオーディエンスの id を取得します。これは、オーディエンスを一から作成する場合に必要な手順です。既存のオーディエンスを更新する場合は、次のセクションに進んでください。

オーディエンスにユーザーを追加する

Custom Audience の id と次のようなサンプルペイロードを用意し、POST accounts/:account_id/custom_audiences/:custom_audience_id/users を使用します。 POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # すべての値はハッシュ化する必要があります。ハッシュ化されていない値は説明目的でのみ使用されています
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

Audience にユーザーを追加するには、operation_type に Update を指定します。新しい Audience インターフェースでは、1 人のユーザーに対して複数のユーザーキーを渡せます。JSON オブジェクト配列内の各オブジェクトは、それぞれ 1 人のユーザーに対応します。上記のサンプルペイロードでは、リクエストによって 2 人のユーザーが Audience に追加されます。1 人は email と handle、もう 1 人は email と twitter_id を持ちます。

オーディエンスからユーザーを削除する

ユーザーを追加する場合と同様に、次の方法でオーディエンスからユーザーを削除できます: POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # すべての値はハッシュ化する必要があります。ハッシュ化されていない値は説明目的でのみ使用されています
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

operation_type は Delete に設定する必要があり、ユーザーはオーディエンスに追加した際に使用したいずれかのキーで照合されます。たとえば、あるユーザーを email と twitter_id でオーディエンスに追加した場合、同じユーザーはこれらのキーのいずれか、すなわち email または twitter_id、あるいはその両方で削除できます。また、同一のリクエスト内で Audience のユーザーを追加および削除することも可能です。このエンドポイントは、1 回のリクエストで複数の operation_type をサポートします。

オプトアウトしたユーザー

グローバルなオプトアウト用エンドポイントの廃止に伴い、パートナーは、いずれかのオーディエンスからオプトアウトしたユーザーを Delete する必要があります。これを実現する方法はいくつかあります。

どのユーザーがどのオーディエンスに属しているかを管理し、各オーディエンスから該当ユーザーを個別に削除する。
広告アカウントに関連付けられているすべてのオーディエンスから、そのユーザーを削除する。

一般的なベストプラクティス

このエンドポイントは、処理が滞留して時間を要するスパイク的なキューを避け、システムへの不要な負荷を防ぐため、ニアリアルタイムのバッチで呼び出すことを強く推奨します。これにより、ユーザーをより早くキャンペーンのターゲティングに利用できるようになります。
成功した API 呼び出しは、リクエストで受信した user オブジェクトの数に対応する success_count と total_count を返します。
このエンドポイントはアトミックです。つまり、リクエスト全体が成功するか、エラーが発生した場合はリクエスト全体が失敗します。エラーレスポンスの場合、API 利用者はエラーを修正し、ペイロード全体を含めてリクエストを再試行することを推奨します。
失敗時には、リトライと併用して指数バックオフ手法の採用を推奨します。たとえば、最初の失敗時は直ちにリトライし、2 回目の失敗後は 1 分後、3 回連続の失敗後は 5 分後にリトライする、など。

API リファレンス

キーワードインサイト

GET insights/keywords/search

キーワードのグループを指定し、該当するTweetのボリュームと、関連キーワード30件のセットを取得します。Tweetボリュームは入力したキーワードのみに対応し、関連キーワードは含みません。許可される時間範囲（end_time - start_time）は最大7日間です。結果は単一のジオ（国）でスコープされる点にご注意ください。 Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	`start_time` と `end_time` で示される時間範囲に対して返されるデータの粒度を指定します。たとえば `HOUR` に設定すると、`start_time` から `end_time` まで各時間ごとのデータポイントが返されます。 Type: enum Possible values: `DAY`, `HOUR`
keywords required	検索を絞り込むためのカンマ区切りのキーワード文字列。すべてのキーワードは相互に OR 条件で評価されます。 Note: 使用できるキーワードは最大10件（`keywords` と `negative_keywords` の合計）です。 Type: string Example: `developers`
start_time required	取得対象を、`start_time` と `end_time` の間の時間枠で収集されたデータに限定します。表記は ISO 8601。 Type: string Example: `2017-07-10T00:00:00Z`
end_time optional	取得対象を、`start_time` と `end_time` の間の時間枠で収集されたデータに限定します。表記は ISO 8601。 Note: 既定値は現在時刻です。 Type: string Example: `2017-07-11T00:00:00Z`
location optional	アカウントのユーザー所在地で結果を絞り込むために使用する、GET targeting_criteria/locations エンドポイントで取得できるターゲティング値。現時点では国レベルのロケーションのみサポートされています。 Type: string Example: `0ce8b9a7b2742f7e`
negative_keywords optional	除外するキーワードのカンマ区切り文字列。すべての除外キーワードは相互に OR 条件で評価されます。 Note: 使用できるキーワードは最大10件（`keywords` と `negative_keywords` の合計）です。 Type: string Example: `rain`

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

応答例*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

テーラードオーディエンスの権限

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

指定したテーラードオーディエンスに関連する権限の一部またはすべての詳細を取得します。 Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
tailored_audience_id required	リクエストで対象とするテーラードオーディエンスの参照。 Type: string Example: `1nmth`
count optional	個々のリクエストで取得を試みるレコード数を指定します。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: `8x7v00oow`
granted_account_ids optional	識別子のカンマ区切りリストを指定して、レスポンスを目的のアカウントに限定します。最大 200 個の ID を指定できます。 Type: string Example: `18ce54aymz3`
sort_by optional	サポートされる属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	識別子のカンマ区切りリストを指定して、レスポンスを目的のテーラードオーディエンス権限に限定します。最大 200 個の ID を指定できます。 Type: string Example: `ri`
with_total_count optional	`total_count` レスポンス属性を含めます。 Note: このパラメータと `cursor` は相互排他です。 Note: `total_count` を含むリクエストはレート制限が低く、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

指定したオーディエンスを特定のアカウントと共有できるようにする新しい権限オブジェクトを作成します。注記: テーラードオーディエンスの権限を作成または変更するには、そのオーディエンスが権限の変更を試みているアカウントに所有されている必要があります。特定のオーディエンスのレスポンスに含まれる is_owner 属性を確認することで、テーラードオーディエンスの所有者かどうかを確認できます。注記: オーディエンスは同一ビジネス配下の広告アカウント間でのみ共有できます。あるいは、そのオーディエンスを所有する広告アカウントが SHARE_AUDIENCE_OUTSIDE_BUSINESS アカウント機能を有している場合に限り、共有できます。 Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
granted_account_id required	テーラードオーディエンスへの権限を付与したい相手先アカウント。 Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id` に付与するテーラードオーディエンスへのアクセス権の種類。 Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	リクエストで操作するテーラードオーディエンスの参照。 Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

指定した Tailored Audience の共有権限を取り消します。注: Tailored Audience の権限を作成または変更するには、対象のオーディエンスが権限を変更しようとしているアカウントの所有物である必要があります。特定のオーディエンスについては、そのレスポンスに含まれる is_owner 属性を確認することで所有者かどうかをチェックできます。取り消し後は、付与されていたアカウント（granted_account_id）が今後のキャンペーンで当該オーディエンスをターゲットにできないことを保証します。既存のキャンペーンは共有オーディエンスを引き続き使用して配信されます。キャンペーンが停止されたり、オーディエンスがキャンペーンから削除されたりすることはありません。オーディエンス共有権限の取り消し後は、そのキャンペーンをコピーすることはできません。 Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須です。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
tailored_audience_id required	リクエストで操作対象の Tailored Audience を指す参照。 Type: string Example: `1nmth`
tailored_audience_permission_id required	リクエストで操作対象の Tailored Audience 権限を指す参照。 Type: string Example: `ri`

Example Request DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

ターゲットオーディエンス

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

指定した custom_audience_id をターゲットにしているアクティブ、またはすべてのラインアイテムとキャンペーンの一覧を取得します

Name	Description
account_id required	利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるカスタムオーディエンスの参照。 Type: string Example: `2906h`
with_active optional	`false` の場合、`servable=false` のステータスを持つラインアイテムも含めます。 Type: boolean Default: `true` Possible values: `true`, `false`
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: `8x7v00oow`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "テストキャンペーン",
          "line_items": [
            {
              "id": "5gzog",
              "name": "テスト広告項目",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "無題のキャンペーン",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

カスタムオーディエンスのユーザー

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

このエンドポイントでは、パートナーが指定の custom_audience_id に対してユーザーの追加・更新・削除を行えます。ユーザーごとに複数のユーザー識別子タイプも受け付けます。リクエストの users フィールドで提供されるすべてのデータは、partner_user_id を除き、SHA256 でハッシュ化し、正規化されている必要があります。 バッチリクエスト

現在の最大バッチサイズは、このエンドポイントに限り 2500 です。バッチサイズはリクエストあたりの操作数（Update/Delete）で決まります。例えば、1 つの配列に 2500 を超える操作オブジェクト（{"operation_type": "Update/Delete", [..] }）が含まれるとエラーになります。
このエンドポイントが受け付けるリクエストの最大 POST ボディサイズは 5,000,000 バイトです。
このエンドポイントのレート制限は 1 分あたり 1500 件です。
すべてのパラメータはリクエストボディで送信され、Content-Type は application/json が必須です。
バッチリクエストはグループ単位で一括して成功または失敗し、エラー・成功いずれの場合も、API レスポンスは初期リクエストのアイテム順序を保持します。

バッチレスポンス Ads API が返すレスポンスには、success_count と total_count の 2 つのフィールドが含まれます。これらの値は常に等しくなる必要があり、バックエンドで処理されたリクエスト内のレコード数を示します。リクエストボディで送信したレコード数が success_count および total_count と等しくない場合はエラーとして扱い、再試行が必要です。 バッチエラー

リクエストレベルのエラー（例: 最大バッチサイズ超過）は、レスポンスの errors オブジェクトに表示されます。
アイテムレベルのエラー（例: 必須パラメータの不足）は、レスポンスの operation_errors オブジェクトに表示されます。
operation_errors 内のエラーのインデックスは、対応するエラーメッセージとともに、入力アイテムのインデックスを指します。

リソースURL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

パラメーター

Name	Description
operation_type 必須	`users` グループ単位で実行される操作タイプ。 Type: enum Possible values: `Update`, `Delete`
params 必須	`users` 配列、`effective_at` と `expires_at` のタイムスタンプを含む JSON オブジェクト。 Type: JSON
users 必須	各ユーザーのすべてのパラメーターを含む JSON オブジェクトの配列。 Type: JSON
effective_at 任意	カスタムオーディエンスの関連付けが有効になる UTC 時刻。 ISO 8601 で表現。既定値は現在の日時。 Type: string Example: `2017-07-05T07:00:00Z`
expires_at 任意	カスタムオーディエンスの関連付けが失効する UTC 時刻。指定した時刻は `effective_at` の値より後である必要があります。 ISO 8601 で表現。既定値はリクエストのタイムスタンプから 13 か月後。 Type: string Example: `2017-07-05T07:00:00Z`

users オブジェクトのマルチキー方式に従い、このオブジェクトの各要素は以下のとおりです。

Name	Description
email 任意	ユーザーのメールアドレス。 Type: Array[String]
device_id 任意	IDFA/AdID/Android ID。 Type: Array[String]
handle 任意	ユーザーの @handle。 Type: Array[String]
twitter_id 任意	ユーザーの X ID。 Type: Array[String]
phone_number 任意	ユーザーの電話番号。 Type: Array[String]
partner_user_id 任意	パートナーのシステムにおけるユーザーの ID。 Type: Array[String]

例: リクエスト

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

応答例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

カスタムオーディエンスの権限

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

指定したカスタムオーディエンスに関連する権限の一部またはすべての詳細を取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるカスタムオーディエンスを参照します。 Type: string Example: `1nmth`
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳しくは Pagination を参照してください。 Type: string Example: `8x7v00oow`
granted_account_ids optional	識別子のカンマ区切りリストを指定して、レスポンスを目的のアカウントのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: `18ce54aymz3`
sort_by optional	サポートされる属性で昇順または降順に並べ替えます。詳しくは Sorting を参照してください。 Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	識別子のカンマ区切りリストを指定して、レスポンスを目的のカスタムオーディエンス権限のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: `ri`
with_total_count optional	`total_count` レスポンス属性を含めます。注意: このパラメータと `cursor` は相互排他です。注意: `total_count` を含むリクエストには、現在 15 分あたり 200 のより低いレート制限が適用されます。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

指定したオーディエンスを特定のアカウントと共有できるようにする、新しい権限オブジェクトを作成します。注: カスタムオーディエンスの権限を作成または変更するには、権限の変更を行おうとしているアカウントが当該オーディエンスを所有している必要があります。特定のオーディエンスに対するレスポンス内の is_owner 属性を確認することで、カスタムオーディエンスの所有者かどうかを確認できます。注: オーディエンスは、同一ビジネス配下の広告アカウント間でのみ共有できます。あるいは、そのオーディエンスを所有する広告アカウントに SHARE_AUDIENCE_OUTSIDE_BUSINESS アカウント機能が付与されている場合に限り、ビジネス外の共有も可能です。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
granted_account_id required	カスタムオーディエンスの権限を付与したい相手先アカウント。 Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id` に付与するカスタムオーディエンスへのアクセス権限の種類。 Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
custom_audience_id required	このリクエストで操作対象となるカスタムオーディエンスの参照。 Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

指定した Custom Audience の共有権限を取り消します。注: Custom Audience の権限を作成または変更するには、操作しようとしているアカウントが当該オーディエンスを所有している必要があります。特定のオーディエンスのレスポンスに含まれる is_owner 属性を確認することで、Custom Audience の所有者かどうかを確認できます。取り消し後は、付与先アカウント（granted_account_id）が今後のキャンペーンでそのオーディエンスをターゲティングできないことを保証します。既存のキャンペーンは共有オーディエンスを用いて引き続き配信されます。キャンペーンは停止されず、オーディエンスがキャンペーンから削除されることもありません。オーディエンス共有権限の取り消し後は、このキャンペーンをコピーできません。 Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となる Custom Audience への参照。 Type: string Example: `1nmth`
custom_audience_permission_id required	リクエストで操作対象となる Custom Audience の権限への参照。 Type: string Example: `ri`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

カスタムオーディエンス

GET accounts/:account_id/custom_audiences

現在のアカウントに関連付けられている一部またはすべてのカスタムオーディエンスの詳細を取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
count optional	リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: `8x7v00oow`
permission_scope optional	自分が所有するリスト、または自分と共有されているリストにレスポンスをフィルタリングします。デフォルトでは、このパラメータを指定しない場合は自分が所有するオーディエンスのみが表示されます。 Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	`name` によってリソースを絞り込むための任意のクエリ。 Note: 大文字小文字を区別しない前方一致でマッチングします。 Type: string Min, Max length: `1`, `255`
sort_by optional	対応する属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string Example: `created_at-asc`
custom_audience_ids optional	コンマ区切りの識別子リストを指定して、目的のカスタムオーディエンスのみにレスポンスを絞り込みます。最大200個のIDを指定できます。 Type: string Example: `1nmth`
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	レスポンスに `total_count` 属性を含めます。 Note: このパラメータと `cursor` は併用できません。 Note: `total_count` を含むリクエストはレート制限が低く、現在は15分あたり200に設定されています。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

GET accounts/:account_id/custom_audiences/:custom_audience_id

現在のアカウントに関連付けられている特定のカスタムオーディエンスを取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるカスタムオーディエンスを参照する識別子。 Type: string Example: `2906h`
with_deleted optional	削除済みの結果を含めるかどうか。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

POST accounts/:account_id/custom_audiences

現在のアカウントに関連付けられた新しいプレースホルダーのカスタムオーディエンスを作成します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
name required	このオーディエンスの表示名。一意の名前を使用する必要があります。従わない場合はエラーになります。 Type: string Example: `ads api users`
description optional	このオーディエンスの説明。 Type: string Example: `Collection of all users of the Ads API`

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

PUT accounts/:account_id/custom_audiences/:custom_audience_id

現在のアカウントに紐づく特定のCustom Audienceを更新します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべてのAdvertiser APIリクエストで一般的に必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるCustom Audienceの参照。 Type: string Example: `2906h`
name optional	このオーディエンスの表示名。重複しない一意の名前を使用する必要があります。満たさない場合はエラーになります。 Type: string Example: `ads api users`
description optional	このオーディエンスの説明。 Type: string Example: `Collection of all users of the Ads API`

Example Request PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

POST batch/accounts/:account_id/custom_audiences

Custom Audiences をバッチで作成できます。オーディエンスの概要は Custom Audiences Overview ページを参照してください。注: このバッチエンドポイントは現在 クローズドベータ で、一部の広告主のみが利用できます。ベータ期間中は、モバイルのカスタムオーディエンスに基づく Flexible Audiences のみ作成可能です。 バッチリクエスト

現在の最大バッチサイズは 10 です。
すべてのパラメータはリクエストボディで送信し、Content-Type は application/json が必須です。
バッチリクエストはグループとして一括で成功または失敗し、エラー/成功いずれの API レスポンスでも、初期リクエストのアイテム順序が保持されます。

バッチレスポンス Batch API のレスポンスは順序付きのアイテムコレクションを返します。それ以外は、対応する単一アイテムのエンドポイントと構造は同一です。 バッチエラー

リクエストレベルのエラー（例: 最大バッチサイズ超過）はレスポンスの errors オブジェクトで示されます。
アイテムレベルのエラー（例: 必須パラメータの欠如）はレスポンスの operation_errors オブジェクトで示されます。

Flexible Audiences

Flexible Audiences は作成後に変更できません。
Flexible Audience を作成するために、Custom Audiences はブールロジックを組み合わせたツリー構造で渡されます。
1 つの Flexible Audience を作成する際に使用できる Custom Audiences のリーフノードは最大 10 個です。

Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Parameters

名前	説明
account_id 必須	対象となるアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。型: string 例: `18ce54d4x5t`
audience_type 必須	作成するオーディエンスの種類。型: enum 可能な値: `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments 必須	ターゲットにしたい Custom Audience のメンバーのサブセットを定義するオブジェクトを含む配列。各オブジェクトには `custom_audience_id`、`frequency`、`frequency_comparator`、`lookback_window`、`negate`、必要に応じて追加の `child_segments` を含める必要があります。型: array
name 必須	オーディエンスの表示名。一意の名前を使用する必要があります。従わない場合はエラーになります。型: string 例: `my_flexible_audience_name`
operation_type 必須	各アイテムに対して実行される操作タイプ。型: enum 可能な値: `Create`, `Update`, `Delete`
boolean_operator 条件付き必須	親（包含）オブジェクト内の子セグメント間の論理関係。親オブジェクトの child_segments が空でない場合に必須です。型: enum 可能な値: `AND`, `OR`
lookback_window 条件付き必須	ユーザーが特定のアクションを行い、指定の custom audience の条件を満たした期間（日数）を示す整数値。型: int 可能な値: `1`, `7`, `14`, `30`
segments 条件付き必須	ターゲットにしたい Custom Audience のメンバーのサブセットを定義する `boolean_operator` と `child_segments` を含むオブジェクト。型: object
custom_audience_id 条件付き必須	子セグメントとして使用する custom audience の id。型: string 例: `tyfo`
frequency 任意	ユーザーが特定のアクションを行い、指定の custom audience の条件を満たした頻度を、lookback window 内で示す整数値。型: int デフォルト値: `1`
frequency_comparator 任意	リクエストで渡された `frequency` に対する比較演算子。注: 以下の値では、`GTE` は「以上」、`LT` は「未満」などを表します。型: string 可能な値: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` デフォルト値: `NUM_GTE`
negate 任意	セグメントを否定し、組み合わせから除外します。型: boolean デフォルト値: `true` 可能な値: `true`, `false`

リクエスト例 POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

応答例

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

現在のアカウントに属する指定の Custom Audience を削除します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	本リクエストで操作するカスタムオーディエンスを参照する識別子。 Type: string Example: `2906h`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

リーチ対象外リスト

GET accounts/:account_id/do_not_reach_lists

現在のアカウントに関連付けられている「Do Not Reach List」の一部またはすべての詳細を取得します。注: account_id に対して保持できる「Do Not Reach List」は最大1件です。 Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
with_deleted optional	削除済みの結果を含めるかどうか。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "リーチ除外リスト",
          "description": "DNRLテスト",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/do_not_reach_lists

現在のアカウントに関連付けられた新しい Do Not Reach List を作成します。注: account_id につき Do Not Reach List は最大 1 件までです Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
description optional	このオーディエンスの説明。 Type: string Example: `A list of users to exclude`

Example Request POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude Example Response

    {
      "request": {
        "params": {
          "description": "除外するユーザーのリスト",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach List",
        "description": "除外するユーザーのリスト",
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

このエンドポイントでは、指定された do_not_reach_list_id にユーザーを追加、更新、削除できます。このエンドポイントで有効なユーザー識別子の種類はメールアドレスのみです。リクエストの emails フィールドで提供されるすべてのデータは、SHA256 でハッシュ化し、正規化する必要があります。 注意事項

account_id は Do Not Reach List を最大 1 つしか保持できません
このリストに追加されるユーザーには、現在のタイムスタンプから 13 か月未満となるように expires_at タイムスタンプを必ず設定する必要があります
Do Not Reach List API は effective_at タイムスタンプを受け付けず、デフォルトで現在のタイムスタンプが使用されます
Do Not Reach List は、アカウント内の任意またはすべてのカスタムオーディエンスからユーザーを削除するものではなく、アカウントで配信されるすべてのキャンペーンに対する除外ターゲティングとして機能します

バッチリクエスト

現在の最大バッチサイズは「このエンドポイントに対して」2500 です。バッチサイズは、リクエストごとの操作数（Update/Delete）で決まります。例えば、1 つの配列内に 2500 を超える操作オブジェクト（{"operation_type": "Update/Delete", [..] }）があるとエラーになります。
このエンドポイントが受け付ける最大リクエスト POST ボディサイズは 5,000,000 バイトです。
このエンドポイントのレート制限は 1 分あたり 1500 回です
すべてのパラメータはリクエストボディで送信され、application/json の Content-Type が必要です。
バッチリクエストはグループ単位で一括して成功または失敗し、エラー/成功いずれの場合も API レスポンスは初回リクエストのアイテム順序を保持します。

バッチレスポンス Ads API によって返されるレスポンスには、success_count と total_count の 2 つのフィールドが含まれます。これらの値は常に等しくなければならず、バックエンドが処理したリクエスト内のレコード数を表します。リクエストボディで送信したレコード数が success_count および total_count と等しくない状況はエラーとして扱い、再試行が必要です。 バッチエラー

リクエストレベルのエラー（例: 最大バッチサイズ超過）は、レスポンスの errors オブジェクトに表示されます。
アイテムレベルのエラー（例: 必須パラメータの欠落）は、レスポンスの operation_errors オブジェクトに表示されます。
operation_errors におけるエラーのインデックスは、入力アイテム内のインデックスを指し、対応するエラーメッセージが付随します

Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	リクエストで操作対象となる Do Not Reach List への参照。 Type: string Example: `2906h`
operation_type required	実行する `users` グループごとの操作タイプ。 Type: enum Possible values: `Update`, `Delete`
params required	`emails` 配列と `expires_at` タイムスタンプを含む JSON オブジェクト。 Type: JSON
users required	個々のユーザーに関するすべてのパラメータを含む JSON オブジェクトの配列。 Type: JSON
expires_at optional	ユーザーの関連付けが失効する UTC 時刻。指定時刻は現在のタイムスタンプより後である必要があります。ISO 8601 で表現します。デフォルトは現在のタイムスタンプから 13 か月後です。 Type: string Example: `2017-07-05T07:00:00Z`

users オブジェクトの multi-key アプローチに基づき、このオブジェクトの各要素は以下で説明します:

名前	説明
email 任意	ユーザーのメールアドレス型: Array[String]
phone_number 任意	ユーザーの電話番号型: Array[String]

リクエスト例

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

例のレスポンス

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

現在のアカウントに属する指定の Do Not Reach List を削除します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id Parameters なし Example Request DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp Example Response

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "配信除外リスト",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }

X 広告API

基本

リソース

測定

​カスタムオーディエンス

​概要

​オーディエンスに関するFAQ

​CRM

​パートナーIDマッチング要件

​標準のマッチング要件

​カスタムセグメントリストのファイル命名と操作

​オーディエンスの作成と更新

​ハッシュ化の手順

​Eメールの正規化

​デバイス ID の正規化

​X ユーザーIDの正規化

​ID Sync 統合

​ピクセル URL

​ピクセルパラメータ

​ID同期ピクセル：

​カスタムオーディエンスのユーザーデータ

​カスタムオーディエンス: Web

​Audience API の連携

​概要

​新しいカスタムオーディエンスを作成する

​オーディエンスにユーザーを追加する

​オーディエンスからユーザーを削除する

​オプトアウトしたユーザー

​API リファレンス

​キーワードインサイト

​GET insights/keywords/search

​テーラードオーディエンスの権限

​GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

​ターゲットオーディエンス

​GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

​カスタムオーディエンスのユーザー

​POST accounts/:account_id/custom_audiences/:custom_audience_id/users

​リソースURL

​パラメーター

​例: リクエスト

​応答例

​カスタムオーディエンスの権限

​GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

​カスタムオーディエンス

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​リーチ対象外リスト

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

​POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

カスタムオーディエンス

概要

オーディエンスに関するFAQ

CRM

パートナーIDマッチング要件

標準のマッチング要件

カスタムセグメントリストのファイル命名と操作

オーディエンスの作成と更新

ハッシュ化の手順

Eメールの正規化

デバイス ID の正規化

X ユーザーIDの正規化

ID Sync 統合

ピクセル URL

ピクセルパラメータ

ID同期ピクセル：

カスタムオーディエンスのユーザーデータ

カスタムオーディエンス: Web

Audience API の連携

概要

新しいカスタムオーディエンスを作成する

オーディエンスにユーザーを追加する

オーディエンスからユーザーを削除する

オプトアウトしたユーザー

API リファレンス

キーワードインサイト

GET insights/keywords/search

テーラードオーディエンスの権限

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

ターゲットオーディエンス

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

カスタムオーディエンスのユーザー

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

リソースURL

パラメーター

例: リクエスト

応答例

カスタムオーディエンスの権限

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

カスタムオーディエンス

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

リーチ対象外リスト

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id