Send audience members

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

Advertiser Data Partner

In this quickstart, you complete the following steps:

1. Prepare a Destination to receive audience data.
2. Prepare audience data to send.
3. Build an IngestionService request for audience members.
4. Send the request with the Google APIs Explorer.
5. 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": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

• Set the operatingAccount to the product 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,[e-mail],[e-mail],
2,[e-mail], [e-mail],[e-mail]
3,[e-mail],[e-mail]  ,
4,[e-mail],[e-mail],

Email addresses have the following formatting and hashing requirements:

1. Remove all leading, trailing, and intermediate whitespace.
2. Convert the email address to lowercase.
3. Hash the email address using the SHA-256 algorithm.
4. 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,[e-mail],[e-mail],
2,[e-mail],[e-mail],[e-mail]
3,[e-mail],[e-mail],
4,[e-mail],[e-mail],

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 [e-mail] and [e-mail] 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": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "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
}

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

Send the request

1. Copy the request body using the copy button at the top right of the sample.
2. Click the API button in the toolbar.
3. Paste the copied request body into the Request body box.
4. 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"
}

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

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 about best practices.
• Learn about limits and quotas.