Create a Customer Match audience

Create a Customer Match audience by sending a CreateUserListRequest.

Construct the request body

Create a UserList resource. Here are the common fields to set.

displayName

Required The display name of the list. The name must be unique among all of the lists owned by the account.

description

A brief description of the list.

integrationCode

An ID from your system.

membershipDuration

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.

If using JSON, calculate the number of seconds by multiplying the duration days by 86400 (the number of seconds per day). Then set the value to the multiplication result, followed by s. For example, if you want a membership duration of 90 days, use the value 7776000s since 90 * 86400 = 7776000.

If using the protocol buffer format, use the convenience method for constructing a Duration object based on the number of days, if such a convenience method exists. For example, the protobuf-java-util library for Java has a fromDays() convenience method. Otherwise, calculate the number of seconds by multiplying the duration days by 86400 (the number of seconds per day), and use the result to set the seconds field of the Duration object.

Required fields for Customer Match

The ingestedUserListInfo field is required for a Customer Match audience.

Here are the fields to set on the IngestedUserListInfo based on the type of data you want to use to add audience members to the list.

Contact information list

Set the following fields if you want to use contact information (hashed email addresses, phone numbers, or addresses) to define your audience members:

uploadKeyTypes

Set to a list containing the CONTACT_ID upload key type.

The uploadKeyTypes list must contain only one entry.

contactIdInfo

Set to a ContactIdInfo message with the dataSourceType set to the appropriate value from the DataSourceType enum.

Mobile ID list

Set the following fields if you want to use mobile IDs to define your audience members:

uploadKeyTypes

Set to a list containing the MOBILE_ID upload key type.

The uploadKeyTypes list must contain only one entry.

mobileIdInfo

Set to a MobileIdInfo message:

• Set the dataSourceType to the appropriate value from the DataSourceType enum.

• Set the keySpace to IOS or ANDROID.

• Set the appId to the string that uniquely identifies the mobile application from which the data was collected.

  • For iOS, the ID string is the 9 digit string that appears at the end of the App Store URL. For example, 476943146 for the "Flood-It!" app with App Store link https://apps.apple.com/us/app/flood-it/id476943146.

  • For Android, the ID string is the application's package name. For example, com.labpixies.flood for the "Flood-It!" app with Google Play link https://play.google.com/store/apps/details?id=com.labpixies.flood.

Construct the request

To create a Customer Match audience, construct a create request for the UserList resource.

1. Set the parent field to the resource name of the account. The resource name must follow the format accountTypes/{accountType}/accounts/{account_id}.

2. Use the UserList you constructed for the body of the request.

3. If your credentials aren't for a Google Account that's a user on the parent, set headers as described in Configure destinations and headers.

Here are sample requests in JSON for the different types of user information. Each request sets the membershipDuration to 2592000s, where 2592000 is the number of seconds in 30 days. Click the Open in API Explorer button to try a request.

{
    "description": "Customer Match for contact info",
    "displayName": "Contact info audience",
    "ingestedUserListInfo": {
        "contactIdInfo": {
            "dataSourceType": "DATA_SOURCE_TYPE_FIRST_PARTY"
        },
        "uploadKeyTypes": [
            "CONTACT_ID"
        ]
    },
    "membershipDuration": "2592000s"
}

{
    "description": "Customer Match for mobile IDs",
    "displayName": "Mobile ID audience",
    "ingestedUserListInfo": {
        "mobileIdInfo": {
            "dataSourceType": "DATA_SOURCE_TYPE_FIRST_PARTY",
            "keySpace": "ANDROID",
            "appId": "com.labpixies.flood"
        },
        "uploadKeyTypes": [
            "MOBILE_ID"
        ]
    },
    "membershipDuration": "2592000s"
}

Send the request

Send the request and, if required, include request headers.

If the request succeeds, the response contains the created UserList with the id and name populated. Make note of the values in these fields since you need them in requests to add audience members to the audience.

If the request fails, inspect the errors to determine the cause of the failure, update the request and headers to fix any issues, and then send the updated request and headers.