Send audience members

AI-generated Key Takeaways

This quickstart guide familiarizes users with the Data Manager API by outlining steps to prepare a destination, format and prepare audience data, build an ingestion request, send the request, and understand responses.
Audience data, such as email addresses, must be formatted by removing whitespace, converting to lowercase, hashing with SHA-256, and encoding using hex or Base64.
Requests require a combination of destination information and formatted audience member data in the request body.
Successful requests return a requestId for tracking, while failures provide error details.
You can send audience members to multiple destinations in a single request by using destination references within the request body.

You can work through this quickstart to get familiar with the Data Manager API. Choose the version of the quickstart you want to see:

In this quickstart, you complete the following steps:

Prepare a Destination to receive audience data.
Prepare audience data to send.
Build an IngestionService request for audience members.
Send the request with the Google APIs Explorer.
Understand success and failure responses.

Prepare a destination

Before you can send data, you need to prepare the destination to send the data to. Here's a sample Destination for you to use:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

Set the operatingAccount to the account type and ID of the account that will receive the audience data.

Prepare audience data

Consider the following sample data in a comma-separated file. Each line in the file corresponds to one member of the audience, and each member has up to three email addresses.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

Email addresses have the following formatting and hashing requirements:

Remove all leading, trailing, and intermediate whitespace.
Convert the email address to lowercase.
Hash the email address using the SHA-256 algorithm.
Encode the hash bytes using hexadecimal (hex) or Base64 encoding. The examples in this guide use hex encoding.

Here's the formatted data:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

And here's the data after being hashed and encoded:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

Here's a sample AudienceMember for the formatted, hashed, and encoded email addresses of dana@example.com and danam@example.com from the first row of the input data:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

Build the request body

Combine the Destination and userData for the request body:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}

Update the placeholders in the body, such as OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID, and AUDIENCE_ID with the values for your account and destination.
Set validateOnly to true to validate the request without applying the changes. When you're ready to apply the changes, set validateOnly to false.
Set termsOfService to indicate that the user has accepted the Customer Match terms of service.
Note this request indicates that consent is granted, and doesn't use encryption.

Send the request

Copy the request body using the copy button at the top right of the sample.
Click the API button in the toolbar.
Paste the copied request body into the Request body box.
Click the Execute button, complete the authorization prompts, and review the response.

Success responses

A successful request returns a response with an object containing a requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Record the requestId returned so you can retrieve diagnostics as each destination in the request is processed.

Failure responses

A failed request results in an error response status code such as 400 Bad Request, and a response with error details.

For example, an email_address containing a plain text string instead of a hex encoded value produces the following response:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

An email_address that isn't hashed and is only hex encoded produces the following response:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Send events for multiple destinations

If your data contains audience members for different destinations, you can send them in the same request by using destination references.

For example, if you have an audience member for user list ID 11112222 and another audience member for user list ID 77778888, send both audience members in a single request by setting the reference of each Destination. The reference is user-defined—the only requirement is that each Destination has a unique reference. Here's the modified destinations list for the request:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

Set the destination_references of each AudienceMember to send it to one or more specific destinations. For example, here's an AudienceMember that's only for the first Destination, so its destination_references list only contains the reference of the first Destination:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

The destination_references field is a list, so you can specify multiple destinations for an audience member. If you don't set the destination_references of an AudienceMember, the Data Manager API sends the audience member to all of the destinations in the request.

Next steps

Configure authentication and setup your environment with a client library.
Learn about the formatting, hashing, and encoding requirements for each type of data.
Learn how to encrypt user data.
Learn how to retrieve diagnostics for your requests.
Learn about best practices.
Learn about limits and quotas.

Audiences overview