Use the field mappings to upgrade each step of your Customer Match workflow from the Google Ads API to the Data Manager API: - [Audience management field mappings](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#manage) contains field mappings for creating, updating, and retrieving audiences. - [Ingestion field mappings](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#ingestion) contains field mappings for adding or removing audience members. ## Audience management field mappings Use the mappings in the tables to map a [`UserList`](https://developers.google.com/google-ads/api/reference/rpc/latest/UserList) in the Google Ads API to its [`UserList`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userlist) equivalent in the Data Manager API. | [`UserList` (Google Ads API)](https://developers.google.com/google-ads/api/reference/rpc/latest/UserList) | [`UserList` (Data Manager API)](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userlist) | Notes | |---|---|---| | `resource_name` | `name` | See [Resource names](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#resource-names) for details. | | `id` | `id` | | | `read_only` | `read_only` | | | `name` | `display_name` | **Required** | | `description` | `description` | **Required** | | `membership_status` | `membership_status` | | | `integration_code` | `integration_code` | | | `membership_life_span` | `membership_duration` | The duration an audience member remains in the list after added. The value must correspond to whole days. If not set, defaults to the maximum. Format the value using the [Timestamp format](https://developers.google.com/data-manager/api/devguides/concepts/formatting#timestamp_format). | | `size_for_display` | `size_info.display_network_members_count` | | | `size_range_for_display` | No equivalent. | Use the `size_info.display_network_members_count` for size information. | | `size_for_search` | `size_info.search_network_members_count` | | | `size_range_for_search` | No equivalent. | Use the `size_info.search_network_members_count` for size information. | | `type` | No equivalent. | | | `access_reason` | `access_reason` | | | `account_user_list_status` | `account_access_status` | | | `closing_reason` | `closing_reason` | | | `eligible_for_search` | `target_network_info.eligible_for_search` | | | `eligible_for_display` | `target_network_info.eligible_for_display` | | | `match_rate_percentage` | `ingested_user_list_info.contact_id_info.match_rate_percentage` | | | `basic_user_list` | `ingested_user_list_info.pseudonymous_id_info` | Not used for Customer Match. | | `crm_based_user_list` | `ingested_user_list_info` | **Required.** See [Customer Match audience information](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#audience-info). | | No equivalent. | `ingested_user_list_info.pair_id_info` | Not used for Customer Match. | | No equivalent. | `ingested_user_list_info.partner_audience_info` | Not used for Customer Match. | | `logical_user_list` | No equivalent. | Not used for Customer Match. | | `logical_user_list` | No equivalent. | Not used for Customer Match. | | `lookalike_user_list` | No equivalent. | Not used for Customer Match. | | `rule_based_user_list` | No equivalent. | Not used for Customer Match. | | `similar_user_list` | No equivalent. | Not used for Customer Match. | ### Customer Match audience information In the Google Ads API, you must set the `crm_based_user_list` field to a [`CrmBasedUserListInfo`](https://developers.google.com/google-ads/api/reference/rpc/latest/CrmBasedUserListInfo) when creating a Customer Match audience. In the Data Manager API, set the equivalent attributes by setting the `ingested_user_list_info` field to an [`IngestedUserListInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingesteduserlistinfo), then set the required fields for Customer Match and the type of user data. ### Contact information `upload_key_types` : Set to a list containing `CONTACT_ID`. This is equivalent to setting the `upload_key_type` to `CONTACT_INFO` in the Google Ads API. `contact_id_info` : Set to a [`ContactIdInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#contactidinfo). Set `data_source_type` to `DATA_SOURCE_TYPE_FIRST_PARTY`. This is equivalent to setting the `data_source_type` to `FIRST_PARTY` in the Google Ads API. ### Mobile IDs `upload_key_types` : Set to a list containing `MOBILE_ID`. This is equivalent to setting the `upload_key_type` to `MOBILE_ADVERTISING_ID` in the Google Ads API. `mobile_id_info` : Set to a [`MobileIdInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#mobileidinfo). - Set `data_source_type` to `DATA_SOURCE_TYPE_FIRST_PARTY`. This is equivalent to setting the `data_source_type` to `FIRST_PARTY` in the Google Ads API. - Set `key_space` to `IOS` or `ANDROID`. The Data Manager API requires this value. This differs from the Google Ads API, where the key space is inferred from the `app_id`. - Set `app_id` to the string that uniquely identifies the mobile application from which the data was collected. Use the same format you use for the `app_id` in the Google Ads API. ### User IDs `upload_key_types` : Set to a list containing `USER_ID`. This is equivalent to setting the `upload_key_type` to `CRM_ID` in the Google Ads API. `user_id_info` : Set to a [`UserIdInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#useridinfo). Set `data_source_type` to `DATA_SOURCE_TYPE_FIRST_PARTY`. This is equivalent to setting the `data_source_type` to `FIRST_PARTY` in the Google Ads API. ### Resource names The Data Manager API uses a different resource name format than the Google Ads API. Google Ads API : In the Google Ads API, a `UserList` resource name uses the format: `customers/{customer_id}/userLists/{user_list_id}` Data Manager API : In the Data Manager API, a `UserList` resource name uses the format: `accountTypes/{accountType}/accounts/{account}/userLists/{userList}` ## Upload field mappings Use the mappings in the tables to map an [`AddOfflineUserDataJobOperationsRequest`](https://developers.google.com/google-ads/api/reference/rpc/latest/AddOfflineUserDataJobOperationsRequest) in the Google Ads API to its [`IngestAudienceMembersRequest`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingestaudiencemembersrequest) equivalent in the Data Manager API. ### Request fields | [`AddOfflineUserDataJobOperationsRequest`](https://developers.google.com/google-ads/api/reference/rpc/latest/AddOfflineUserDataJobOperationsRequest) (Google Ads API) | [`IngestAudienceMembersRequest`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingestaudiencemembersrequest) (Data Manager API) | Notes | |---|---|---| | - `customer_id` field - `customer_match_user_list_metadata` field of `OfflineUserDataJob` - `developer-token` request header - `login-customer_id` request header - `linked-customer-id` request header | `destinations` | See [Customer and audience fields](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#customer-audience). | | `consent` from the [`customer_match_user_list_metadata`](https://developers.google.com/google-ads/api/reference/rpc/latest/CustomerMatchUserListMetadata) of [`OfflineUserDataJob`](https://developers.google.com/google-ads/api/reference/rpc/latest/OfflineUserDataJob) | `consent` | Optional default consent settings for audience members in the request. You can override this value for an individual audience member by setting the `consent` field of `AudienceMember`. | | No equivalent | `encoding` | **Required:** Set to the [`Encoding`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#encoding) used for `UserIdentifier` values. | | No equivalent | `encryption_info` | Set if the request contains encrypted values. See [Encryption](https://developers.google.com/data-manager/api/devguides/concepts/encryption) for details. | | `job_id` | No equivalent | Use the `request_id` returned in the response to retrieve [diagnostics](https://developers.google.com/data-manager/api/devguides/diagnostics). | | `enable_partial_failure` | No equivalent | The Data Manager API doesn't support partial failure. If any field of an `IngestAudienceMembersRequest` fails validation, the Data Manager API rejects the entire request. Retrieve processing errors using [diagnostics](https://developers.google.com/data-manager/api/devguides/diagnostics). | | `enable_warnings` | No equivalent | The Data Manager API doesn't report warnings in the response. Retrieve processing warnings using [diagnostics](https://developers.google.com/data-manager/api/devguides/diagnostics). | | `validate_only` | `validate_only` | | | `operations` | `audience_members` | The list of audience members. See the [Audience member fields section](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#audience-member) for details. | | No equivalent | `terms_of_service` | **Required.** Set to indicate that the user has accepted or rejected the terms of service for Customer Match. | ### Customer and audience fields The Google Ads API only supports uploading audience members to *one* audience per job.In addition, the `developer-token` request header is required, and you set the `login-customer-id` and `linked-customer-id` [request headers](https://developers.google.com/google-ads/api/docs/concepts/call-structure#request_headers) for different authentication scenarios. The Data Manager API supports [sending audience members for multiple audiences in a single request](https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members#multiple-destinations). The Data Manager API doesn't require a developer token, and you specify login and linked customer information using fields of a `Destination` instead of request headers. Check out [Configure destinations](https://developers.google.com/data-manager/api/devguides/concepts/destinations) for more information about destinations. The Data Manager API doesn't support removing all members of an audience. In the Google Ads API, you can remove all members of an audience by setting the `remove_all` field of an [`OfflineUserDataJobOperation`](https://developers.google.com/google-ads/api/reference/rpc/latest/OfflineUserDataJobOperation) to `true`. Here's how to map the Google Ads API fields for a single audience to the equivalent fields in a `Destination`: | Google Ads API | [`Destination`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#destination) (Data Manager API) | Notes | |---|---|---| | `customer_id` of the request | `operating_account` | Set the `account_id` to the customer ID of the audience. Set the `account_type` of the `operating_account` to `GOOGLE_ADS`. | | `developer-token` request header | No equivalent | A developer token is not required for the Data Manager API. | | `login-customer-id` request header | `login_account` | Set the `account_id` to the customer ID of the login account. Set `account_type` to `GOOGLE_ADS` if the login account is a Google Ads account, or `DATA_PARTNER` if the login account is a data partner account. | | `linked-customer-id` request header | `linked_account` | If you're accessing the `operating_account` using a [partner link](https://developers.google.com/data-manager/api/devguides/accounts/partner-links), set the `account_id` to the customer ID of the linked account and set `account_type` to `DATA_PARTNER`. Otherwise, don't set the `linked_account` field. | | `user_list` from the [`customer_match_user_list_metadata`](https://developers.google.com/google-ads/api/reference/rpc/latest/CustomerMatchUserListMetadata) of [`OfflineUserDataJob`](https://developers.google.com/google-ads/api/reference/rpc/latest/OfflineUserDataJob) | `product_destination_id` | **Required.** Set to the numeric ID of the audience. Don't use the resource name of the `UserList`. | | No equivalent | `reference` | A user-defined identifier for the `Destination`. Set this field if you are [sending audience members for multiple audiences in a single request](https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members#multiple-destinations). | ### Audience member fields | [`UserData`](https://developers.google.com/google-ads/api/reference/rpc/latest/UserData) (Google Ads API) | [`AudienceMember`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#audiencemember) (Data Manager API) | Notes | |---|---|---| | `consent` | `consent` | Set to specify the consent for the audience member. Both APIs use a similar `Consent` object (ad_user_data, ad_personalization). For the Data Manager API, you can also set consent for all audience members in a request by setting the request-level `consent` field. | | `transaction_attribute` | No equivalent. | Not applicable to Customer Match. | | `user_attribute` | No equivalent. | Not applicable to Customer Match. | | `user_identifiers` | - `mobile_data` - `user_id_data` - `composite_data` - `user_data` - `ip_data` | Populate the field that corresponds to the type of data you're sending for audience members. See [User identifier fields](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#user-identifiers) for details. | ### User identifier fields In the Google Ads API, whether you're sending contact information, mobile IDs, or user IDs, you use [`UserIdentifier`](https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier). The Data Manager API uses a different approach, with different fields for each type of data. In the Data Manager API, populate the field that corresponds to the type of data you're sending: ### Contact information If using contact information such as email address, phone number, or address information, set `composite_data` to a [`CompositeData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#compositedata) with a separate entry in `user_data.user_identifiers` for each contact information item. While `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#google.ads.datamanager.v1.AudienceMember.FIELDS.google.ads.datamanager.v1.UserData.google.ads.datamanager.v1.AudienceMember.user_data` is still supported, we recommend using `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#google.ads.datamanager.v1.AudienceMember.FIELDS.google.ads.datamanager.v1.CompositeData.google.ads.datamanager.v1.AudienceMember.composite_data` to ensure your integration is prepared for future improvements. See [Composite data](https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members#composite-data) for details. | `https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier` (Google Ads API) | `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#useridentifier` (Data Manager API) | Notes | |---|---|---| | `address_info` | `address` | See [Address fields](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/upgrade/field-mappings#address) for details. | | `hashed_email` | `email_address` | Set to the [formatted and hashed](https://developers.google.com/data-manager/api/devguides/concepts/formatting) email address. You can also [encrypt the hashed email address](https://developers.google.com/data-manager/api/devguides/concepts/encryption). | | `hashed_phone_number` | `phone_number` | Set to the [formatted and hashed](https://developers.google.com/data-manager/api/devguides/concepts/formatting) phone number. You can also [encrypt the hashed phone number](https://developers.google.com/data-manager/api/devguides/concepts/encryption). | | `user_identifier_source` | No equivalent. | | #### Address fields Here are the field mappings between [`OfflineUserAddressInfo`](https://developers.google.com/google-ads/api/reference/rpc/latest/OfflineUserAddressInfo) in the Google Ads API and [`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo) in the Data Manager API. Use these mappings if you're using contact information to populate your Customer Match audience. > [!IMPORTANT] > **Important:** Only set the `address` field if you have a value for every required field. Otherwise, your Data Manager API request fails. This differs from the Google Ads API, which allows incomplete address information but then silently ignores it during the matching process. | `https://developers.google.com/google-ads/api/reference/rpc/latest/OfflineUserAddressInfo` (Google Ads API) | `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo` (Data Manager API) | Notes | |---|---|---| | `city` | No equivalent. | | | `country_code` | `region_code` | **Required** | | `hashed_first_name` | `given_name` | **Required.** Set to the [formatted and hashed](https://developers.google.com/data-manager/api/devguides/concepts/formatting) given name. You can also [encrypt the hashed given name](https://developers.google.com/data-manager/api/devguides/concepts/encryption). | | `hashed_last_name` | `family_name` | **Required.** Set to the [formatted and hashed](https://developers.google.com/data-manager/api/devguides/concepts/formatting) family name. You can also [encrypt the hashed family name](https://developers.google.com/data-manager/api/devguides/concepts/encryption). | | `hashed_street_address` | No equivalent. | | | `postal_code` | `postal_code` | **Required** | | `state` | No equivalent. | | #### IP address The Data Manager API supports including IP addresses for Customer Match uploads in addition to user identifiers. These are provided in [`CompositeData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#compositedata), which bundles [`UserData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userdata) and [`IpData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ipdata). Providing these fields together can help improve match rates. See [IP ingestion for Customer Match](https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members#send-ip-timestamp) for more details. > [!NOTE] > **Note:** While we encourage you to include IP address and timestamp, match rate improvements from these signals are expected to begin in Q3 2026. | Google Ads API | `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#compositedata` (Data Manager API) | Notes | |---|---|---| | No equivalent. | `ip_data.ip_address` | Set to the raw IPv4 or IPv6 address. See [IP address format](https://developers.google.com/data-manager/api/devguides/concepts/formatting#userdata_format) guidance. | | No equivalent. | `ip_data.observe_start_time` | Set to the timestamp in [RFC 3339 format](https://developers.google.com/data-manager/api/devguides/concepts/formatting#timestamp_format) when the IP address was first observed. | | No equivalent. | `ip_data.observe_end_time` | Set to the timestamp in [RFC 3339 format](https://developers.google.com/data-manager/api/devguides/concepts/formatting#timestamp_format) when the IP address was last observed. | | `user_identifiers` | `user_data` | Set to a [`UserData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userdata) object. | ### Mobile IDs If using mobile IDs, set `mobile_data` to a [`MobileData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#mobiledata) with an entry in `mobile_ids` for each ID. | `https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier` (Google Ads API) | `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#mobiledata` (Data Manager API) | Notes | |---|---|---| | `mobile_id` | `mobile_ids` | Set to the list of [mobile IDs](https://developers.google.com/data-manager/api/devguides/concepts/formatting#mobiledata_format) for the audience member. In the Google Ads API, you add a *separate* `UserIdentifier` with `mobile_id` for every mobile ID for the audience member. In the Data Manager API, add a *single* `MobileData` with `mobile_ids` set to the list of all of the mobile IDs for the audience member. | | `user_identifier_source` | No equivalent. | | ### User IDs If using user IDs, set `user_id_data` to a [`UserIdData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userdata), and set `user_id` to the user ID for the audience member. | `https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier` (Google Ads API) | `https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#useriddata` (Data Manager API) | Notes | |---|---|---| | `third_party_user_id` | `user_id` | In the Google Ads API, you add a *separate* `UserIdentifier` with `third_party_user_id` for every user ID for the audience member. In the Data Manager API, set the `user_id_data` field to a `UserIdData`, and set its `user_id` field to the user ID for the audience member. You can't send multiple user IDs for the same audience member. | | `user_identifier_source` | No equivalent. | |