メインコンテンツへスキップ

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

​
概要

パートナーがCustom Audiencesを作成する方法はいくつかあります。 なお、類似カスタムオーディエンスはターゲティングから除外できません。さらに、同一の広告ラインアイテム（広告グループ）で、カスタムオーディエンスとその類似オーディエンスの両方を同時にターゲティングすることはできません。 オーディエンス管理 オーディエンスは、オーディエンスパートナーおよび X Ads API パートナー経由で管理できます。API では、カスタムオーディエンスにアクセス・保守するための一連の endpoint を提供しています。 カスタムオーディエンス情報向けに、次の 2 つの endpoint を提供しています。 オーディエンスのアップロードと管理の詳細は、Audience API ガイドをご覧ください。 処理時間 一般的に、オーディエンスの変更は 6～8 時間ごとに実行されるバッチで処理されます。変更の処理中でも、更新対象の既存オーディエンス自体には影響はありません。この時間枠内では、各オーディエンスにつき、追加の更新は 1 回、削除の更新も 1 回を超えないことを推奨します。 ターゲティング オーディエンスは、X が所有・運営するクライアント上で過去 90 日以内にアクティブだったユーザーが少なくとも 100 人に一致する場合にのみターゲティング可能です。GET accounts/:account_id/custom_audiences/:custom_audience_id は、一致ユーザー数が少なすぎるためにターゲティングできない可能性がある場合にその旨を示します。 Audience API (CRM)
image2
オーディエンスまたは API パートナーがハッシュ化済み識別子のリストを提供し、X が照合して、X 上のメディアバイイングに利用可能なセグメントを生成します。パートナーは Audience API を使用してこれらのオーディエンスを作成できます。 動作の流れ
image3
Web MPP オーディエンスパートナーとの連携時に、X 上のメディアバイイングでターゲティングするセグメントを識別する標準的なクッキーマッチングプロセスを提供しています。加えて、広告主は X Web Event Tag を設定してウェブサイトのユーザーデータを収集し、対応する Custom Audience を作成できます。 セットアップ手順
image0
 動作の流れ
image1
Mobile 詳細については、Custom Audiences from Mobile Apps のブログ記事をご覧ください。 Flexible Flexible audiences により、広告主は既存のカスタムオーディエンス、またはそのサブセットに基づいて、オーディエンスの組み合わせを作成して保存できます。カスタムオーディエンスのメンバーのサブセットは、インタラクションの最近度と頻度に基づいてターゲティングできます。 カスタムオーディエンスの制限付きユースケース 制限事項の詳細はこちら

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

Q: 大量のデータを送信しましたが、オーディエンスサイズがTOO_SMALLと表示されるのはなぜですか？ A: 現在、データはリアルタイムでオーディエンスに追加されていますが、オーディエンスサイズを算出する処理ジョブは一定時間経過後にのみ実行されます。数時間後にはUIに正しいオーディエンスサイズが表示されるはずです。 Q: オーディエンスデータの送信を完了し、24時間以上待ちましたが、まだそのオーディエンスをターゲティングできません。次に何をすべきですか？ A: 次の点をご確認ください。
  • 渡しているユーザーIDが正しく、形式が壊れていないこと。
  • 渡しているオーディエンス名が正しく、過去のメンバーシップ更新内容と一致していること。
  • POSTコマンドのレスポンスを確認してください。
  • ID Syncピクセルが正しく実装されていること、またID Syncプロセスで説明されているとおり、該当サイトに十分な数のユーザーが訪問し、ユーザーのマッピングが行われていることを確認してください。メンバーシップ更新でマッピングされていないユーザーは、ターゲティング可能なユーザーに変換されません。
上記すべてが正しく動作していることを確認できた場合は、可能な限り詳細な情報を添えてXのプロダクト担当者にご連絡ください（望ましい情報の例はGuide to Partner Inboundsを参照）。 Q: そのendpointは何回呼び出せますか、またどのようなアルゴリズムで呼ぶべきですか？ 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: 標準IDとは何ですか？
  • メールアドレス、デバイスID、Xの@handleまたはIDを指します。
Q: HMACキーはどのように取得しますか？
  • 暗号化されたメールで提供します。公開PGP鍵をmpp-inquiry@x.comにお送りください。すべてが問題なく動作することを確認するため、テストメールを送信します。確認が取れ次第、HMACキーをお送りします。
Q: 提供されたHMACキーを用いてハッシュ処理が機能したことをどのように検証しますか？
  • Xがテストファイル（サンプルのメールアドレス、デバイスIDなどを含む）と、検証用の結果hashファイルを提供します。
Q: フルデータマッチファイルにファイルサイズの制限はありますか？
  • いいえ、フルデータマッチファイルにサイズ制限はありません。
Q: フルデータマッチファイルの処理にはどれくらい時間がかかりますか？
  • Xがファイルを受領してから、処理には約1日かかります。

​
CRM

image0
本書は、Custom Audiences の CRM パートナー向け統合について、ファイル形式およびデータ交換プロセスの詳細を説明します。 概要 Company は、顧客に代わり、ハッシュ化済みの一般的なユーザー識別子（例：メールアドレス）またはパートナーのユーザー ID のリストを X に提供し、ブラインドマッチを実行して、ターゲティング用の X ユーザー ID のリストを生成します。ターゲティング用セグメントは、ads.x.com のキャンペーン設定でファイル名により指定された、当該広告主の特定の @handle で利用可能になります。 Company からのすべてのファイルは、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を持つ場合：
共通ユーザー識別子 1p_user_1
共通ユーザー識別子 2p_user_1
共通ユーザー識別子 3p_user_1
*共通ユーザー識別子のハッシュ化手順については、以下のセクションを参照してください 2. カスタムセグメントリスト 企業はp_user_idの形式でユーザーのリストを提供し、X上でのターゲティング用に顧客向けのカスタムオーディエンスを作成します。
  • 行区切り値
  • p_user_id
    • （上記の1. 完全データマッチセクションで提供されたものと同じ。完全データマッチで提供された値がハッシュ化されている場合、企業はオーディエンスファイルで同じハッシュ化された値を提供します。提供された値がハッシュ化されていない場合、企業はハッシュ化されていない値を提供します。）

​
標準的なマッチング要件

企業がすべての顧客ユーザー識別子のマッピングに標準のidを使用していない場合は、以下のプロセスを推奨します。 カスタムセグメントリスト 企業は、顧客に代わって共通ユーザー識別子をhash化したリストをXに直接提供し、カスタムオーディエンスを作成します。 このファイルの形式は次のとおりです:
  • 行区切りの値
  • hash化された共通ユーザー識別子（例: emailアドレス）
  • 以下のファイル命名規則に従う
  • 以下のemailアドレスのhash化手順（Hashing Directions）に従う

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

ファイルの処理内容はファイル名によって決まり、利用可能な操作と一般的なファイル命名規則は次のとおりです: audiencename_partnername.handle.operation.filetype
  • audiencename: カスタムオーディエンスの名称。ads.x.com のキャンペーン設定 UI でオーディエンス選択時に表示される名前です（例: brand_loyalty_card_holders）。
  • partnername: 広告主に代わって data を提供する企業名（例: 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-mailの正規化

具体的には、先頭と末尾のスペースを削除し、メールアドレスをすべて小文字に変換します。 例: 元のE-mailアドレス: 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 ではないものの、データのグルーピング（例：@handle の Customer List）は広告主にとって非公開であるため、引き続きハッシュ化されます。X の ID のハッシュ化には、SHA-256 ハッシュアルゴリズムと、当社がデータパートナーに提供する共通のソルトを使用するという同一の要件が適用されます。X ID と @username の両方からは空白を削除してください。ただし、User ID の正規化は不要です。@username は正規化のため小文字にしてください。また、@ 記号は username の一部に含めないでください。 生の ID 形式は次のとおりです:
  • User ID: 27674040
  • @username: testusername
ハッシュ化された User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 ハッシュ化された @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

​
ID 同期の統合

p_id を用いて data を送信するパートナーは、広告主またはパートナーのユーザー id を X のユーザー id にマッピングするための ID 同期プロセスを実施する必要があります。これにより、広告主は X 上で自社のユーザーセグメントを直接ターゲティングできます。パートナーは、メンバーシップ更新を送信する際に、パラメータ user_identifier_type の値を TALIST_PARTNER_USER_ID または TAWEB_PARTNER_USER_ID のいずれかに設定する必要があります。
  • Web のみ: 以下のとおり、広告主のサイトにピクセルを設置することで実施できます。
  • List: CRM ページで説明されている任意の方法を使用して実施できます。

​
ピクセル URL

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

​
ピクセルパラメータ

パラメータ説明
p_idX によって割り当てられたパートナーの 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 に提供する必要があります。送信するファイルの形式は以下のとおりです。
列番号列名列の型説明
1Partner IDstring「partner id」は、各パートナーを一意に識別するために X がパートナーに付与する ID です。
2The user’s id in the partner systemstringp_user_id は、パートナーがユーザーを識別するために使用する一意の ID です。これらのオプトアウトユーザーを含むファイルは、TON upload endpoint を使用してアップロードし、アップロードした data のパスを以下の Global Opt Out endpoint に送信してください: PUT accounts/:account_id/custom_audiences/global_opt_out。
メンバーシップ更新の送信 endpoint ドキュメントに記載のとおり、POST custom_audience_memberships endpoint 経由でユーザーを送信する場合は、クッキーベースのマッチングを有効にするために customer ID を渡す必要があります。p_id を用いて data を送信するパートナーは、user_identifier_type を TALIST_PARTNER_USER_ID または TAWEB_PARTNER_USER_ID に設定することが必須です。 その他の手順は、Real-Time Audience API Integration Guide に記載されている内容と同一です。

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

このドキュメントでは、[Custom Audience]/x-ads-api/audiences のユーザーデータ形式を説明します。 データの正規化 デバイス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をhash化
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#出力
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d
ハッシュ用の追加のコードサンプルは github.com/xdevplatform/ads-platform-tools で参照できます。

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

info.png
情報 パートナーは広告主に代わり、ターゲティングのための 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 endpoint を通じて X が定期的に取得できるよう提供します。これらのターゲティングファイルは X によって定期的に取り込まれ、その後 X の UI で利用可能になります。 X Secure Pixel X セキュアピクセルは次のとおりです: https://analytics.x.com/i/adsct?p&#95;user&#95;id=xyz&amp;p&#95;id=123 p_user_id - xyz はパートナーが提供するパートナー側のユーザー ID を表します p_id - 123 はパートナーに割り当てられた一意の ID（X により付与）を表します パートナー HTTPS Endpoint とターゲティングユーザーファイル パートナーは、ターゲティングファイルを定期的に取り込むために使用できる HTTPS endpoint と認証情報（ユーザー名/パスワード）を X に提供する必要があります。サンプルの HTTPS endpoint は次のとおりです: 
https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz
%Y - 年のフォーマットコード（YYYY） %M - 月のフォーマットコード（MM） %D - 日のフォーマットコード（DD） 送信されるdataは次のファイルで構成されます:
  1. パートナーターゲティングユーザーファイル
  2. ターゲティングコンバージョンファイル
すべてのファイルはTSV形式で、各行の個々のfieldsはタブ文字で区切られます。正当なフィールド値自体にタブ文字が含まれることはありません。 許可されるXのIP範囲: パートナーendpointへのアクセスを許可できるIPの範囲は以下のとおりです。
  • 199.16.156.0/22
  • 199.59.148.0/22
パートナーターゲティングユーザーファイル:
列番号列名列の型説明
1partner idstring「partner id」は、各パートナーを一意に識別するためにXがパートナーに付与するIDです。
2advertiser idstring「advertiser id」は広告主の@handleです。
3p_user_idstring「p_user_id」は、パートナーがユーザーを識別するために使用する一意のIDです。
3confidence scoreinteger「confidence score」は任意です。推奨範囲は0〜100です。ユースケースがリターゲティングの場合、スコア「100」は直接リターゲティングされたユーザーを意味します。0〜99のスコアは、類似オーディエンスに対する信頼度のレベルを示します。
4segment labelstring「segment label」は任意です。パートナーは、たとえば製品カテゴリの指定に「segment label」を使用できます。この「segment label」を使用することを推奨します。ads.x.comのUIにおけるCustom Audiencesの人間可読名であるためです。
注記: 新しいパートナーターゲティングファイルを受領するたびに、別途合意がない限り、これはパートナーがターゲティングを推奨するユーザーの完全なリストであり、増分ではないものと想定します。このパートナーターゲティングファイルの配信頻度は各パートナーと取り決めます。期待どおりにパートナーターゲティングファイルを受領できない場合は、あらかじめ定義された有効期限付きで前回のバージョンを使用します。

​
Audience API の統合

​
概要

Audience API は Ads API の v4 の一部としてリリースされ、従来の Audiences endpoint に対して複数の改善が行われました。この新しい endpoint は新しい Audience 処理バックエンドを基盤としており、安定性・堅牢性・信頼性の面で向上しています。本ガイドの目的は、Audience API と従来の Audience のアップロードおよび管理プロセスとの違いを明確にすることです。  リファレンスは Audience API のリファレンスドキュメントページをご参照ください。  注: すべての Audience のユーザーデータはアップロード前に SHA-256 でハッシュ化する必要があります。受け入れ可能なユーザー識別子の種類やデータ正規化の詳細は user data ページをご覧ください。 Audience 機能の変更点 v4 以降、以下の Custom Audiences に対する変更が導入されており、非推奨の endpoint は Ads API の v3 の提供終了後に利用できなくなります:
  • 非推奨 TON Upload:
    • 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
  • 非推奨 Real Time Audiences:
    • POST custom_audience_memberships
  • Custom Audience:
    • Custom Audience のすべての endpoint において、リクエストおよびレスポンスから list_type パラメータが削除されます。このパラメータは以前、Audience のユーザー識別子タイプ（例: email、X User ID など）を識別するために使用されていましたが、現在は同一の Audience に対して複数のユーザー識別子を受け付けられるようになったため、この値は不要になりました。
  • 一般:
    • Audience のルックバック期間は、（以前の 30 日から）過去 90 日以内にアクティブだったユーザーに合致するように更新されました
    • ターゲット可能とするために必要な一致ユーザーの最小数は、（以前の 500 ユーザーから）100 ユーザーに引き下げられました
前提条件
  • X Ads API へのアクセス
  • Audience endpoint へのアクセスには allowlist への追加が必要です。以下のフォームに記入し、2018-08-01 より前に初回承認されている場合は新しい X Ads Products and Services Agreement に同意してください
Audience アップロードプロセス 以下の表は、旧来と新しい Audience 作成フローの主な相違点を示します。詳細はこの後の節をご覧ください:
プロセスのステップAudience API（非推奨）TON Upload
シェル Audience の作成[POST custom_audience endpoint]/x-ads-api/audiences を使用して作成可能[POST custom_audience endpoint]/x-ads-api/audiences を使用して作成可能
新規ユーザーの追加Audience endpoint で operation_type Update を使用POST custom_audience_changes endpoint で operation ADD を使用
ユーザーの削除Audience endpoint で operation_type Delete を使用POST custom_audience_changes endpoint で operation REMOVE を使用
ユーザーのオプトアウトAudience endpoint で operation_type Delete と、当該ユーザーが属する対応する custom_audience_id を使用Global opt-out endpoint を使用
注 TON Upload 経路で更新またはオプトアウトされるすべての audience は、TON Upload endpoint を通じて対応するリストがアップロードされ、custom_audience_changes endpoint を使用して Audience に関連付けられている必要があります。 レート制限 Audience API endpoint のレートリミットはアカウントあたり 1500/1min です。単一のペイロードで送信可能なユーザー数に制限はありません。ペイロードに対する制約は次のとおりです:
  1. 操作の合計数: 2500 operations
  2. 最大ペイロードサイズ: 5,000,000 bytes
Audience ユーザー管理 新しい Audience を作成するには、以下の手順が必要です

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

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

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

カスタムオーディエンスの id と、以下のようなサンプルペイロードを用いて、POST accounts/:account_id/custom_audiences/:custom_audience_id/users を実行します。 POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom&#95;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&#95;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、またはその両方で削除できます。 また、同一のリクエスト内でオーディエンスへのユーザーの追加と削除を同時に行うことも可能です。該当の endpoint は、1 回のリクエストで複数の operation_type をサポートします。

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

グローバルなオプトアウト endpoint の廃止に伴い、パートナーは任意の Audiences からオプトアウトしたユーザーを DELETE する必要があります。これを実現する方法はいくつかあります。
  1. どのユーザーがどの Audiences に属しているかを管理し、各 Audience からこれらのユーザーを個別に削除する。
  2. Ads アカウントに関連付けられている Audiences から、そのユーザーをすべて削除する。
一般的なベストプラクティス
  • 処理に時間を要するスパイク的なキューを避け、全体としてシステムに不要な負荷をかけないため、この endpoint はニアリアルタイムのバッチで呼び出すことを強く推奨します。これにより、ユーザーをより早くキャンペーンのターゲティングに利用できるようになります。
  • 成功した API 呼び出しは、リクエストで受信した user オブジェクトの数に対応する success_count と total_count を返します。
  • この endpoint はアトミックです。つまり、リクエスト全体が成功するか、いずれかにエラーがある場合はリクエスト全体が失敗します。エラー応答が返された場合は、API 利用者はエラーを修正し、ペイロード全体を含めてリクエストを再試行することを推奨します。
  • 失敗時には、再試行時に指数バックオフ方式を使用することを推奨します。例えば、最初の失敗時は直ちに再試行し、2回目の失敗後は1分後、3回連続の失敗後は5分後に再試行する、という具合です。

​
API リファレンス

​
キーワードインサイト

​
GET insights/keywords/search

キーワードのグループを指定すると、対応するTweetのボリュームと、関連キーワード30件のセットを取得します。Tweetのボリュームは入力したキーワードのみに対応し、関連キーワードは含みません。 許可される時間範囲（end_time - start_time）は最大7日間です。 結果は単一の地域（国）でスコープされる点にご注意ください。 リソースURL https://ads-api.x.com/12/insights/keywords/search パラメータ
NameDescription
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 endpoint から取得するターゲティング値。現時点では国レベルのロケーションのみサポートしています。

Type: string

Example: 0ce8b9a7b2742f7e
negative_keywords
optional		除外するキーワードのカンマ区切り文字列。すべてのネガティブキーワードは相互に OR 条件で評価されます。

Note: キーワードは最大10個まで（keywords と negative_keywords の合計）。

Type: string

Example: rain
リクエスト例 
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
        ]
      }
    }

​
Tailored Audience の権限

​
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
NameDescription
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",
          "作成日時": "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
NameDescription
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",
        "作成日時": "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 の共有権限を取り消します。 Note: Tailored Audience の権限を作成または変更するには、操作を行うアカウントが当該オーディエンスの所有者である必要があります。特定のオーディエンスに対するレスポンスの is_owner 属性を確認することで、Tailored Audience の所有権を確認できます。 取り消し後は、付与先のアカウント（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
NameDescription
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",
        "作成日時": "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 をターゲットとしている、アクティブなものまたはすべてのラインアイテムおよびキャンペーンの一覧を取得します
NameDescription
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

この endpoint は、パートナーが指定された custom_audience_id に対してユーザーの追加、更新、削除を行えるようにします。また、ユーザーごとに複数のユーザー識別子タイプも受け付けます。 リクエストの users フィールドで提供されるすべての data は、partner_user_id を除き、SHA256 でハッシュ化し、正規化されている必要があります。 バッチリクエスト
  • 現在の最大バッチサイズは、この endpoint に対しては 2500 です。バッチサイズは、リクエストあたりの操作数（Update/Delete）によって決まります。たとえば、1つの配列内に 2500 を超える操作オブジェクト（{"operation_type": "Update/Delete", [..] }）があるとエラーになります。
  • この endpoint が受け付けるリクエストの POST ボディの最大サイズは 5,000,000 バイトです。
  • この endpoint のレートリミットは、1 分間のウィンドウあたり 1500 です。
  • すべてのパラメータはリクエストボディで送信され、Content-Type は application/json が必須です。
  • バッチリクエストはグループ単位で成功または失敗が判定され、エラー・成功いずれの場合も API レスポンスで初期リクエストの項目順序が保持されます。
バッチレスポンス X Ads API から返されるレスポンスには、success_count と total_count の 2 つの fields が含まれます。これらの値は常に等しくなければならず、バックエンドで処理されたリクエスト内のレコード数を示します。リクエストボディで送信されたレコード数が 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

​
Parameters

NameDescription
operation_type
required		users グループ単位で実行する操作の種別。

Type: enum

Possible values: Update, Delete
params
required		users 配列、effective_at、expires_at の各タイムスタンプを含む JSON オブジェクト。

Type: JSON
users
required		各ユーザーの全パラメータを含む JSON オブジェクトの配列。

Type: JSON
effective_at
optional		カスタムオーディエンスの関連付けを有効化する UTC 時刻。ISO 8601 で表現。既定値は現在日時。

Type: string

Example: 2017-07-05T07:00:00Z
expires_at
optional		カスタムオーディエンスの関連付けの有効期限となる UTC 時刻。指定時刻は effective_at の値より後である必要があります。ISO 8601 で表現。既定値はリクエストのタイムスタンプから 13 か月後。

Type: string

Example: 2017-07-05T07:00:00Z
users オブジェクトのマルチキー方式に基づき、このオブジェクトの各要素は以下のとおりです:
NameDescription
email
optional		ユーザーのメールアドレス。

Type: Array[String]
device_id
optional		IDFA／AdID／Android ID

Type: Array[String]
handle
optional		ユーザーの @handle。

Type: Array[String]
twitter_id
optional		ユーザーの X ID。

Type: Array[String]
phone_number
optional		ユーザーの電話番号。

Type: Array[String]
partner_user_id
optional		パートナーのシステムにおけるユーザーの 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
NameDescription
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 を含めます。

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/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
NameDescription
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 の共有権限を取り消します。 Note: 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
NameDescription
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

現在のアカウントに関連付けられている一部またはすべての Custom Audiences の詳細を取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters
NameDescription
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		自身が所有する List か、共有されている List にレスポンスを絞り込めます。デフォルトでは、このパラメータを指定しない場合、自身が所有するオーディエンスのみが表示されます。

Type: enum

Default: OWNER
Possible values: OWNER, SHARED
q
optional		name でリソースを絞り込む任意の query。

Note: 大文字小文字を区別しない前方一致でマッチします。

Type: string

Min, Max length: 1, 255
sort_by
optional		サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。

Type: string

Example: created_at-asc
custom_audience_ids
optional		識別子のカンマ区切りリストを指定して、目的の Custom Audiences のみにレスポンスを絞り込みます。最大 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

現在のアカウントに関連付けられている特定の Custom Audiences を取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters
NameDescription
account_id
required		利用するアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
custom_audience_id
required		リクエストで操作対象とする custom audience への参照。

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

現在のアカウントに関連付けられた新規プレースホルダーのCustom Audienceを作成します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters
NameDescription
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
NameDescription
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 ページを参照してください。 注: このバッチ endpoint は現在 クローズドベータで、一部の選定された広告主のみ利用可能です。ベータ期間中は、モバイルのカスタムオーディエンスに基づく Flexible Audiences のみ作成できます。 バッチリクエスト
  • 現在の最大バッチサイズは 10 です。
  • すべてのパラメータはリクエストボディで送信され、Content-Type は application/json が必須です。
  • バッチリクエストはグループとして一括で成功または失敗し、エラー／成功いずれの場合でも、API レスポンスでは初回リクエストのアイテム順が保持されます。
バッチレスポンス Batch API のレスポンスは順序付きのアイテムコレクションを返します。それ以外は、対応する単一アイテムの endpoint と同一の構造です。 バッチエラー
  • リクエストレベルのエラー（例: 最大バッチサイズ超過）は、レスポンスの errors オブジェクトに表示されます。
  • アイテムレベルのエラー（例: 必須パラメータの欠落）は、レスポンスの operation_errors オブジェクトに表示されます。
Flexible Audiences
  • Flexible Audiences は作成後に変更できません（不変）。
  • Custom Audiences はブールロジックの組み合わせによる木構造で渡され、Flexible Audiences を作成します。
  • Flexible Audience の作成に使用できる Custom Audiences のリーフノードは最大 10 個です。
Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Parameters
NameDescription
account_id
required		レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
audience_type
required		作成するオーディエンスの種類。

Type: enum

Possible values: FLEXIBLE, MOBILE_AUDIENCE
child_segments
required		ターゲットにしたい Custom Audience のメンバーのサブセットを定義するオブジェクトを要素とする配列。各オブジェクトには custom_audience_id、frequency、frequency_comparator、lookback_window、negate、および場合によっては追加の child_segments を含める必要があります。

Type: array
name
required		オーディエンスの表示名。一意の名前値を使用してください。そうしない場合はエラーになります。

Type: string

Example: my_flexible_audience_name
operation_type
required		各アイテムに対して実行される操作タイプ。

Type: enum

Possible values: Create, Update, Delete
boolean_operator
sometimes required		親（包含）オブジェクト内における子セグメント間の論理関係。親オブジェクトで child_segments が空でない場合に必須です。

Type: enum

Possible values: AND, OR
lookback_window
sometimes required		ユーザーが特定のアクションを実行し、指定したカスタムオーディエンスの条件を満たした日数の範囲を指定する整数値。

Type: int

Possible values: 1, 7, 14, 30
segments
sometimes required		ターゲットにしたい Custom Audience のメンバーのサブセットを定義する、boolean_operator と child_segments を含むオブジェクト。

Type: object
custom_audience_id
sometimes required		子セグメントとして使用するカスタムオーディエンスの id。

Type: string

Example: tyfo
frequency
optional		ユーザーが特定のアクションを実行し、指定したカスタムオーディエンスの条件を満たした頻度（lookback window 内）を指定する整数値。

Type: int

Default value: 1
frequency_comparator
optional		リクエストで渡された frequency に対する比較演算子。

Note: 以下の値において、GTE は以上、LT は未満、などを表します。

Type: string

Possible values: NUM_GTE, NUM_GT, NUM_EQ, NUM_LTE, NUM_LT Default value: NUM_GTE
negate
optional		セグメントを否定し、組み合わせから除外します。

Type: boolean

Default value: true
Possible values: true, false
Example Request 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
NameDescription
account_id
required		対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定されたアカウントは認証済みユーザーに紐づいている必要があります。

Type: string

Example: 18ce54d4x5t
custom_audience_id
required		リクエストで操作対象となる Custom Audience の参照。

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"
        }
      }
    }

​
配信禁止のList

​
GET accounts/:account_id/do_not_reach_lists

現在のアカウントに関連付けられている Do Not Reach List の一部またはすべての詳細を取得します。 Note: account_id が保持できる Do Not Reach List は最大で 1 つです Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters
NameDescription
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": [
            "小さすぎる"
          ],
          "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
NameDescription
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": "配信除外リスト",
        "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

このendpointは、指定の do_not_reach_list_id にユーザーを追加・更新・削除できます。このendpointは、有効なユーザー識別子としてメールアドレスのみを受け付けます。 リクエストの emails フィールドで提供されるすべてのデータは、SHA256 でハッシュ化し、正規化する必要があります。 注意事項
  • account_id は最大で1つの Do Not Reach List しか持てません
  • このリストに追加されるユーザーは、現在のタイムスタンプから13か月未満に設定された expires_at タイムスタンプを必ず持つ必要があります
  • Do Not Reach List API は effective_at タイムスタンプを受け付けず、デフォルトで現在のタイムスタンプが使用されます
  • Do Not Reach List は、アカウント内の一部またはすべてのカスタムオーディエンスからユーザーを削除しませんが、当該アカウントで配信されるすべてのキャンペーンに対して除外ターゲティングとして機能します
バッチリクエスト
  • 現在の最大バッチサイズは「このendpointでは」2500 です。バッチサイズは、リクエストあたりの操作数（Update/Delete）によって決まります。たとえば、1つの配列内に2500を超える操作オブジェクト（{"operation_type": "Update/Delete", [..] }）が含まれているとエラーになります。
  • このendpointが受け付け可能なリクエストPOST本文の最大サイズは 5,000,000 バイトです。
  • このendpointのレートリミットは1分あたり1500です
  • すべてのパラメータはリクエスト本文で送信され、application/json の Content-Type が必要です。
  • バッチリクエストはグループとして一括で成功または失敗し、エラー・成功いずれのAPIレスポンスでも、最初のリクエストの項目順序が保持されます。
バッチレスポンス X 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
NameDescription
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 オブジェクトのマルチキー方式に基づき、このオブジェクトの各要素を以下に記載します。
NameDescription
email
optional		ユーザーのメールアドレス。

Type: Array[String]
phone_number
optional		ユーザーの電話番号。

Type: Array[String]
Example Request 
`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 を削除します。 リソース URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id パラメータ なし リクエスト例 DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp レスポンス例 
    {
      "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
      }
    }
⌘I