POST /identity/map

複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックしたり、raw UID2 の更新が可能な時期を確認したり、現在の raw UID2 が 発行されてから 90 日未満の場合に前の UID2 を表示することもできます。

Used by: このエンドポイントは、主に広告主とデータプロバイダーによって使用されます。詳細は、Advertiser/Data Provider Integration Overview を参照してください。

UID2 のオプトアウト手順とユーザーがオプトアウトする方法は、User Opt-Out を参照してください。

Version

このドキュメントは、エンドポイントの最新版であるバージョン 3 を対象としています。

必要に応じて、以前のバージョンのドキュメントも利用可能です: POST /identity/map (v2) を参照してください。

Batch Size and Request Parallelization Requirements

以下が必要な情報です:

• 最大リクエストサイズは 1MB です。
• 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマッピングする場合は、1 バッチあたり最大 5,000 アイテムの 順次 バッチで送信します。
• プライベートオペレーターを使用していない限り、バッチを並行して送信しないでください。つまり、単一の HTTP 接続を使用し、ハッシュ化または非ハッシュ化された 直接識別情報 (DII) 値のバッチを連続して送信し、複数の並行接続を作成しないでください。
• メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
  マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする際に処理時間が大幅に増加する可能性があります。ただし、実際に更新が必要なマッピングのみを再計算すると、UID2 の約 1/365 が毎日更新されるため、総処理時間が短縮されます。詳細は、Advertiser/Data Provider Integration Overview と FAQs for Advertisers and Data Providers を参照してください。

Request Format

POST '{environment}/v3/identity/map'

認証の詳細は、Authentication and Authorization を参照してください。

important

すべてのリクエストをシークレットを使用して暗号化する必要があります。詳細は、Encrypting Requests and Decrypting Responses を参照してください。

Path Parameters

Path Parameter	Data Type	Attribute	Description
{environment}	string	Required	テスト（インテグレーション）環境: https://operator-integ.uidapi.com 本番環境: 最適な選択は、ユーザーの所在地によって異なります。ユースケースに適したURLの選択方法や、有効なベース URL の一覧は、Environments を参照してください。

注記

インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報の取得方法は、Getting Your Credentials を参照してください。

Unencrypted JSON Body Parameters

important

暗号化を行う際には、リクエストの JSON 本文に次の 4 つのパラメーターのいずれかをキーと値のペアとして含めてください。

Body Parameter	Data Type	Attribute	Description
email	string array	条件付きで必須	マッピングするメールアドレスのリスト。
email_hash	string array	条件付きで必須	マッピングする正規化済みメールアドレスのBase64エンコードされた SHA-256ハッシュのリスト。
phone	string array	条件付きで必須	マッピングする正規化済み電話番号のリスト。
phone_hash	string array	条件付きで必須	マッピングする正規化済み電話番号のBase64エンコードされた SHA-256ハッシュのリスト。

Request Examples

以下の例は、POST /identity/map エンドポイントへの暗号化されていない JSON リクエスト本文の例です:

{
    "email":[
        "user@example.com",
        "user2@example.com"
    ],
    "phone":[
        "+12345678901",
        "+441234567890"
    ]
}

{
    "email_hash":[
        "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
        "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
    ],
    "phone_hash":[
        "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
        "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
    ]
}

以下は、電話番号の POST /identity/map エンドポイントへの暗号化されたリクエストの例です:

echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [YOUR_CLIENT_API_KEY] [YOUR_CLIENT_SECRET]

詳細および異なるプログラミング言語でのコード例は、Encrypting Requests and Decrypting Responses を参照してください。

Decrypted JSON Response Format

注記

HTTPステータスコードが 200 の場合、レスポンスは暗号化されます。それ以外の場合、レスポンスは暗号化されません。

復号化に成功したレスポンスは、指定されたメールアドレス、電話番号、またはそれぞれのハッシュに対する現在の raw UID2、以前の raw UID2、および更新タイムスタンプを返します。

レスポンスの配列は、入力配列の順序を保持します。レスポンス配列の各要素は、対応するリクエスト配列の同じインデックスにある要素に直接マッピングされます。これにより、結果をその対応する入力と信頼性高く関連付けることができます。

raw UID2 にマッピングできない入力値は、マッピングできなかった理由を含むエラーオブジェクトにマッピングされます。マッピングに失敗するのは、DII が無効であるか、UID2 エコシステムからオプトアウトされている場合です。このような場合、レスポンスステータスは success ですが、raw UID2 は返されません。

以下の例は、入力と対応するレスポンスを示しています。

Input:

{
    "email": [
        "user@example.com",      // Corresponding UID2 rotated in the last 90 days
        "user2@example.com",     // Corresponding UID2 rotated more than 90 days ago
        "invalid email string",  // Invalid identifier
        "optout@example.com"     // DII is opted out
    ]
}

Response:

{
    "body":{
        "email": [
            {
                "u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
                "p": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
                "r": 1735689600000
            },
            {
                "u": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
                "p": null,
                "r": 1735862400000
            },
            { "e": "invalid identifier" },
            { "e": "optout" }
        ],
      "email_hash": [],
      "phone": [],
      "phone_hash": []
    },
    "status": "success"
}

Response Body Properties

レスポンス本文には、以下の表に示すプロパティのいずれかが含まれます。

Body Parameter	Data Type	Description
email	マッピングされた DII オブジェクトの配列	リクエスト内のメールアドレスのリストに対応するマッピングされた DII オブジェクトのリスト。
email_hash	マッピングされた DII オブジェクトの配列	リクエスト内のメールアドレスハッシュのリストに対応するマッピングされた DII オブジェクトのリスト。
phone	マッピングされた DII オブジェクトの配列	リクエスト内の電話番号のリストに対応するマッピングされた DII オブジェクトのリスト。
phone_hash	マッピングされた DII オブジェクトの配列	リクエスト内の電話番号ハッシュのリストに対応するマッピングされた DII オブジェクトのリスト。

DII が正常にマッピングされた場合、マッピングされたオブジェクトには以下の表に示すプロパティが含まれます。

Property	Data Type	Description
u	string	リクエストで提供されたメールアドレスまたは電話番号に対応する raw UID2。
p	string	以下のいずれか: 現在の raw UID2 が過去 90 日以内にローテーションされた場合: 前の値。 現在の raw UID2 が 90 日以上前のものである場合: null。
r	number	Unix タイムスタンプ（ミリ秒単位）で、raw UID2 がリフレッシュされる可能性のある時刻を示します。このタイムスタンプまで、raw UID2 は有効であることが保証されています。

マッピングできなかった入力値に対しては、マッピングされたオブジェクトに以下の表に示すプロパティが含まれます。

Property	Data Type	Description
e	string	マッピングできなかった理由。次のいずれかの値: optout invalid identifier

Response Status Codes

以下の表は、status プロパティの値とその HTTP ステータスコードの対応を示しています。

Status	HTTP Status Code	Description
success	200	リクエストは成功しました。レスポンスは暗号化されます。
client_error	400	リクエストに欠落または無効なパラメーターが含まれていました。
unauthorized	401	リクエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行する権限のないベアラートークンが含まれていました。

status プロパティの値が success 以外の場合、message フィールドには問題に関する追加情報が提供されます。

Migration from v2 Identity Map

以下のセクションでは、以前のバージョンからバージョン 3 への移行に関する一般的な情報とガイダンスを提供します:

• Version 3 Improvements
• Key Differences Between v2 and v3
• Required Changes
• Additional Resources

Version 3 Improvements

V3 Identity Map API は、v2 に比べて以下の改善点を提供します:

• Support for multiple identity types: 1 回のリクエストでメールアドレスと電話番号の両方を処理できます。
• Simpler refresh management: ソルトバケットを監視する代わりに、raw UID2 がリフレッシュタイムスタンプに達したときにマッピングをやり直すだけです。
• Availability of previous raw UID2: ローテーション後90日間、以前のUID2を見ることができます。
• Improved performance: 新しいAPIバージョンは、同じ量の個人データを処理するために、帯域幅を大幅に削減します。

Key Differences Between v2 and v3

以下の表は、バージョン間の主な違いを示しています。

Feature	V2 Implementation	V3 Implementation
必要なエンドポイント	/v2/identity/map + /v2/identity/buckets	/v3/identity/map のみ
リクエストごとのアイデンティティタイプ	単一のアイデンティティタイプのみ	複数のアイデンティティタイプ
リフレッシュ管理	/identity/buckets エンドポイントを介してソルトバケットのローテーションをモニター	refresh_from タイムスタンプを過ぎたときに再マッピング
前の UID2 アクセス	利用不可	90 日間利用可能

Required Changes

以前のバージョンからバージョン 3 へのアップグレードは、以下の手順に従ってください。

1. Update Endpoint URL
2. Update V3 Response Parsing Logic
3. Replace Salt Bucket Monitoring with Refresh Timestamp Logic

1. Update Endpoint URL

エンドポイント URL を更新して、/v3/ 実装を参照するようにしてください。以下の例を参照してください。

# Before (v2)
url = '/v2/identity/map'

# After (v3) 
url = '/v3/identity/map'

2. Update v3 Response Parsing Logic

以下の例に従って、レスポンスの解析ロジックを更新してください。

V2 Response Parsing:

# v2: Process mapped/unmapped objects with identifier lookup
for item in response['body']['mapped']:
    raw_uid = item['advertising_id']
    bucket_id = item['bucket_id']
    original_identifier = item['identifier']
    # Store mapping using identifier as key
    store_mapping(original_identifier, raw_uid, bucket_id)

V3 Response Parsing:

# v3: Process array-indexed responses
for index, item in enumerate(response['body']['email']):
    original_email = request_emails[index]  # Use array index to correlate
    if 'u' in item:
        # Successfully mapped
        current_uid = item['u']
        previous_uid = item.get('p')  # Available for 90 days after rotation, otherwise None
        refresh_from = item['r']
        store_mapping(original_email, current_uid, previous_uid, refresh_from)
    elif 'e' in item:
        # Handle unmapped with reason
        handle_unmapped(original_email, item['e'])

3. Replace Salt Bucket Monitoring with Refresh Timestamp Logic

Salt Bucketのモニタリングを更新して、refresh_from タイムスタンプをチェックし、raw UID2 の更新が必要なものを判断するコードに置き換えます。

以下の例は、リフレッシュタイムスタンプをチェックするための v3 アプローチの実装を示しています:

import time

def is_refresh_needed(mapping):
    now = int(time.time() * 1000)  # Convert to milliseconds
    return now >= mapping['refresh_from']

# Check individual mappings for refresh needs
to_remap = [mapping for mapping in mappings if is_refresh_needed(mapping)]
remap_identities(to_remap)

Additional Resources

• SDK for Java Java 実装 (Advertisers/Data Providers section を参照)

ID マッピングの一般的な情報は、Advertiser/Data Provider Integration Overview を参照してください。