create customer match audience using rest interface

[Coder]

Hello,

I'm trying to create an audience with type customer match and add / remove users to it. I do not want to use the client libraries, as our project just want to use audience upload feature and I don't want to bundle the complete client libraries, rather would like to use the rest interface for the same. 

I have gone through the google ads documentation on how to use rest interface for authentication and also for Creating a Customer Match UserList in this link (java client lib specific). 

I would like get a confirmation that below are supported with the rest  (JSON) interface for Google Ads as I see some of the conversations (conversation-1, conversation-2) in the mid of 2020 says that rest interface does not support adding / removing the users to/from the user list for Google Ads. 

1. Create a Customer Match user list.

     1.1 Create new user list.

     1.2 Create operation.

     1.3 Create service client.
     1.4 Add the user list.

2. Add members to the user list either by using OfflineUserDataJobService / UserDataService

     2.1 Create a new offline user data job.

     2.2 Issue a request to create the offline user data job.

     2.3 Issue a request to add the operations to the offline user data job

     2.4 Print the status message if any partial failure error is returned.

3. Remove members to the user list either by using OfflineUserDataJobService / UserDataService

     3.1 Create a new offline user data job.

     3.2 Issue a request to create the offline user data job.

     3.3 Issue a request to remove the operations to the offline user data job

     3.4 Print the status message if any partial failure error is returned.

Could you please confirm whether the REST JSON for Google Ads is supported for the above operations mainly add and remove users to the user list for customer-match audience type. 

Thanks

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for reaching out. You would be able to use the REST interface to upload the user list.  However, this makes the process more complicated sometimes as it’s not high level programming languages. You could follow one of the client libraries to see what fields are being used and what steps are taken. Also look into the service operation details and the conventions for using the REST API to correctly make the API calls.

Thanks and regards,
Xiaoming, Google Ads API Team
 

Xiaoming Google Ads API Team

ref:_00D1U1174p._5004Q2CPseQ:ref

[Coder]

Hi Xiaoming,

Thank you for the response. I tried to follow the client library and wrote equivalent REST APIs to add customer match user list and added members to it.

However I do not see members added in the GoogleAds UI: Could you please clarify below in this regard.

1) After I added members to the userlist, I don't see that Audience (UserList) in the GoogleAds UI still not populated with data. Below is the text shown on the audience.

• Last upload: Jan 1, 1970 1:00:00 AM
• File name:

2) When I queried the job to check the status of it, it says PENDING. When would this be completed and how can i see the file name and last updated date in the Google Ads UI

{

    "results": [

        {

            "offlineUserDataJob": {

                "resourceName": "customers/**********/offlineUserDataJobs/*******11*",

                "type": "CUSTOMER_MATCH_USER_LIST",

                "status": "PENDING",

                "id": "*******11*"

            }

        }

    ],

    "fieldMask": "offlineUserDataJob.resourceName,offlineUserDataJob.id,offlineUserDataJob.status,offlineUserDataJob.type,offlineUserDataJob.failureReason"

}

3) Difference between OfflineUserDataJobService and UserDataService, which one should be used in the REST scenarios.

Thanks.

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for the reply. I work with Xiaoming and let me provide support to your concern.

For the #1 and #2, if your API request did not encounter any issues, then it most likely encountered the behavior below. However, so that I can further investigate if your API requests encountered any issues, then please provide the complete API request and response logs with request ID generated on your end.
"It takes 6 to 12 hours for a list to be populated with members, so you'll most likely see an "In Progress" status (on the Google Ads UI) if you upload to an audience list more frequently than once every 12 hours."

Moving forward for the #3, you can refer to this document as it discussed the difference of those 2. Both can upload data for user lists, but OfflineUserDataJobs are processed asynchronously. 

Regards,

Ernie John Blanca Tacata Google Ads API Team

ref:_00D1U1174p._5004Q2CPseQ:ref

[Google Ads API Forum Advisor Prod]

Hi,

Please provide the requested details for #1 and #2 via Reply privately to author option.

[Coder]

Hi Ernie,

Thank you for the support. I don't have an option to "Reply to Author (no permission)". However to answer your question, I did not encounter any issues while uploading. I have masked sensitive fields and copied you the request & response.

1) Created a Customer Match user list.

POST: https://googleads.googleapis.com/v6/customers/**********/userLists:mutate

{

    "operations": [

        {

            "create": {

                "readOnly": false,

                "name": "rest-test-audience",

                "description": "A rest-test-audience post request",

                "membershipStatus": "OPEN",

                "membershipLifeSpan": 10000,

                "sizeForDisplay": "0",

                "sizeRangeForDisplay": "LESS_THAN_FIVE_HUNDRED",

                "sizeForSearch": "0",

                "sizeRangeForSearch": "LESS_THAN_FIVE_HUNDRED",

                "type": "CRM_BASED",

                "accessReason": "OWNED",

                "accountUserListStatus": "ENABLED",

                "eligibleForSearch": true,

                "eligibleForDisplay": true,

                "crmBasedUserList": {

                    "uploadKeyType": "CONTACT_INFO",

                    "dataSourceType": "FIRST_PARTY"

                }

            }

        }

    ]

}

Responded with:"resourceName": "customers/**********/userLists/********1*

2) Added members to the user list by using OfflineUserDataJobService 

2.1) created a job

POST: https://googleads.googleapis.com/v6/customers/**********/offlineUserDataJobs:create

{

  "job": {

    "type": "CUSTOMER_MATCH_USER_LIST",

    "customerMatchUserListMetadata": {

      "userList": "customers/**********/userLists/********1*"

    }

  }

}

Responded with:"resourceName": "customers/**********/offlineUserDataJobs/*******11*

2.2) Added members: I wanted to test these behaviours first, then add to the code, hence added only dummy email ids as hashed. I have sent only 6 email ids to the list. 

POST:  https://googleads.googleapis.com/v6/customers/**********/offlineUserDataJobs/*******11*:addOperations

{

    "enablePartialFailure": true,

    "operations": [

      { "create": {

            "userIdentifiers": [

              { "hashedEmail": "b4133380ccd33e9fea010c5c961c1b766f4bf70ca30a4026a65c6854c8921fda"},

              { "hashedEmail": "bc8ff7bc9cbcf078d9e537b9b6098f8d50fe7142086c6aabf6841a7714679c30"},

              { "hashedEmail": "4c7d03d328bed7e9babb9d5abb9216a1b14d5feeb82890816b090521072a5827"},

              { "hashedEmail": "d2b50b25bd11b7bb89b77196400c2224b7207e8a7311bb815eee5f4fdc6e84bd"},

              { "hashedEmail": "5a93546de6d673b505406bb492b1da7a05812cba88627fff7fe403f4504be0b5"},

              { "hashedEmail": "9740b36c2f55f133c73a11133b19db466b2f632aca80d3aef2cb00022f018f15"} ]

          }

      }]

}

Responded with { } as there are no errors.

I queried to check the status of job (after 10hrs now) and below is the response:

{

    "results": [

        {

            "offlineUserDataJob": {

                "resourceName": "customers/**********/offlineUserDataJobs/*******11*",

                "type": "CUSTOMER_MATCH_USER_LIST",

                "status": "PENDING",

                "id": "*******11*"

            }

        }

    ],

    "fieldMask": "offlineUserDataJob.resourceName,offlineUserDataJob.id,offlineUserDataJob.status,offlineUserDataJob.type,offlineUserDataJob.failureReason"

}

Thanks.

[Coder]

Hi Ernie,

Just realised this: Being this as the testing process, I simply added some unknown emails (like cust...@example.com), will it be the case that it did not add? In that case the API  won't throw any error?

Thanks.

[Coder]

Update to the previous message: 

I tried with right 6 gmail ids  and it is still not showing in the UI.

But when I tried manually uploading the csv file using the UI, it says populating, though size is 0.

Please share your insights on them. 

Thanks.

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for reaching out. For the uploaded emails, they are supposed to be google accounts(meaning gmail). However, emails with other domains would not throw any errors. For privacy purposes, the user list size will show as zero until the list has at least 1,000 members. After that, the size will be rounded to the two most significant digits. You could refer to this guide for more information.

Thanks and regards,
Xiaoming, Google Ads API Team

Xiaoming Google Ads API Team

ref:_00D1U1174p._5004Q2CPseQ:ref

[Coder]

Hello again,

Thanks for the clarification. 

Now I have provided 5K actual customer gmail ids, and they are uploaded fine and no errors while uploading. 

But I still see in the UI that it says <100 and too small to serve, also last updated shows as "Last upload: Jan 1, 1970 1:00:00 AM". Its been around 8 hrs that I uploaded.

What else could be a reason for not showing up in the UI? 

Thanks.

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for reaching out. Please note that it takes 6 to 12 hours for a list to be populated with members. Please allow more time for it to be fully populated. Also make sure you are using a production account as test accounts do not serve ads so the remarketing feature is not applicable to the test accounts.

Thanks and regards,
Xiaoming, Google Ads API Team

[Coder]

Hi,

Thank you for the response. To answer your question, the account is a production a/c and not a test one.

Now it is close to 20hrs, but it is still not showing up the Last updated time as updated, it is still with default value "Last upload: Jan 1, 1970 1:00:00 AM". I'm checking the job status and it is still showing as "Pending"

Whatever I have uploaded manually using the UI, it shows the last updated time right as below and also it shows the match rate. 

• Last upload: Feb 18, 2021 7:48:59 AM
• File name: gmail-customers.csv

Could you please help? To reiterate, I'm using REST endpoints to create the userlist and uploading the customer using offlineuserdatajobs.

Thanks.

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for reaching out. Are you using the REST interface directly to upload the users? Could you give it a try to use this client library example? If the issue persists after you try the client library example, please share the complete request and response logs along with the screenshots from the UI via the Reply privately to author option for us to further investigate.

Thanks and regards,
Xiaoming, Google Ads API Team

 

[Coder]

Hi,

Thank you for replying back. As mentioned earlier I don't have permission to reply privately (option is greyed out). 

To answer your question, yes, I tried both client library and rest apis. I tried the same example you provided in the link here: example

However, i found this difference: When I was going through the APIs in detail, i found the OfflineUserDataJobService has RunOfflineUserDataJob which runs the offline user data job.

I have manually executed rest end point to run the both the jobs i created, using client libraries and also rest end-point. I received a response as below for these jobs and no errors shown.

{

    "name": "customers/**********/operations/CjNjd*******MvMTk4MzExO*******vZmZsaW5lVXNlckRhdGFKb*******c0MDAQBg=="

}

After this, when I checked the UI, the audiences were showing  "populating" for a while and later (may be after an hour or two) it went away.

When "populating" was shown in the UI, I verified the job status, and it was RUNNING and after a while it was "SUCCESS".

So the questions are: 

1) it seemed like executing the RunOfflineUserDataJob is mandatory to upload the customer-match info (otherwise job will be PENDING forever) for both Client library example and also for rest-api calls. Is my assumption right? 

2) Also the example did not highlight this step. It says that you can execute a query to get the job status (line 238) and also line 218. But the jobs I created with them never changed the status from PENDING to SUCCESS.

3) the response for run call returned an url with unique id ("name": "customers/**********/operations/CjNjd*******MvMTk4MzExO*******vZmZsaW5lVXNlckRhdGFKb*******c0MDAQBg=="), what is the purpose of it? 

Could you please answer above questions. ? 

Thanks again. 

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for reaching out. Please find my response to your questions below:

 

1.  Executing the RunOfflineUserDataJob is mandatory to upload the customer-match list.

 

2. Once you run the job with RunOfflineUserDataJob, were you able to successfully upload the user list?

 

3. The purpose of using it is to track the operation. You could find more details about it here.

[Dhamayanthi K]

Hi,

Thank you for your reply.

Yes, I was able to upload the user list after I run RunOfflineUserDataJobas rest API.

The clarification needed here is that, the client library example doesn't show this step in the example code provided. So whoever uses the client library example to try out, may not get the user list uploaded to GoogleAds though the user list is created. Was this intentional or is it by mistake? Will the example code be corrected to add run operation so that the job will move to "running" / "success" status from "Pending".

Thanks.

[Google Ads API Forum Advisor Prod]

Hi,

Thank you for the reply.

Since your question is client library specific, then I am afraid that our team could no longer be able to provide any insights as it is already outside of our scope. I would recommend reaching out to the author of the client library instead by posting the concern here as they are more equipped to provide support to your concern.

Regards,

Ernie John Blanca Tacata Google Ads API Team

ref:_00D1U1174p._5004Q2CPseQ:ref

[Coder]

Thank you for the support provided. 

I have contacted the responsible for java client library and added bug there.

[Sohail Amin]

Hi,

I'm also getting this issue, when I run the below code:

user_list_srv = adwords.service(:AdwordsUserListService, 'v201809')    user_list = {
      :xsi_type => 'CrmBasedUserList',
      :name => 'Customer relationship management list #%d' % Time.new.usec,
      :description => 'A list of customers that originated from email addresses',
      # CRM-based user lists can use a membershipLifeSpan of 10000 to indicate
      # unlimited; otherwise normal values apply.
      :membership_life_span => 30,
      :upload_key_type => 'CONTACT_INFO'
    }    operation = {
      :operand => user_list,
      :operator => 'ADD'
    }
    result = user_list_srv.mutate([operation])
    user_list_id = result[:value].first[:id]

I am using the test account and need confirmation if its due to test account or issue in something else??

[Google Ads API Forum Advisor Prod]

Hi Sohail,

Thank you for reaching out. The error indicates that you have issues related to the OAuth2 Verification. Please create the OAuth2 credentials by following this guide and update them in the adwords_api.yml file.

Thanks and regards,
Xiaoming, Google Ads API Team

Xiaoming Google Ads API Team

ref:_00D1U1174p._5004Q2CPseQ:ref

[Prashant Patidar]

Hello,
I have the same use case to run google Apis to manage audience using customer match list user list, 
Can you help me to provide the rest Apis as I m not able to retrieve it from the package.

Thanks for your understanding it would be a great help for me.

The views and opinions included in this email belong to their author and do not necessarily mirror the views and opinions of the company. Our employees are obliged not to make any defamatory clauses, infringe, or authorize infringement of any legal right. Therefore, the company will not take any liability for such statements included in emails. In case of any damages or other liabilities arising, employees are fully responsible for the content of their emails.

[Google Ads API Forum Advisor]

Hi,

Thank you for getting back to us.

I would suggest you follow customers.offlineUserDataJobs guide to perform an addOperation, create and run operation. You can use the customers.offlineUserDataJobs.addOperations endpoint to perform create, remove and removeAll operations. Hope this helps. Let us know if you have any further queries.
 

This message is in relation to case "ref:!00D1U01174p.!5004Q02CPseQ:ref"

Thanks,
 

Google Ads API Team