Resource Names

AI-generated Key Takeaways

• Google Ads API resource names are hierarchical, reflecting the Google Ads account structure, with most resources being sub-resources of the Customer resource.

• Resource names contain unique numerical IDs that identify each object within the hierarchy and can be parsed to derive new resource names.

• Resource names are represented by the resourceName field in JSON request/response bodies.

• Shared objects, like negative keyword lists, have resource names relative to the account used to access them, differing between manager and client accounts.

Name hierarchy

Resource names used in the Google Ads API are hierarchical, mirroring the organization of entities within Google Ads. Almost all resources are sub-resources of the Customer resource, which reflects the fact that almost every API call has to target a specific Google Ads account. For example, campaigns, ad groups, ads, and keywords are all sub-resources of a root customer resource.

Resource	Resource Name
Customer	customers/1234567890
Campaign	customers/1234567890/campaigns/8765432109
AdGroup	customers/1234567890/adGroups/54321098765
AdGroupAd	customers/1234567890/adGroupAds/54321098765~2109876543210

Key Point: Google Ads API uses relative resource names (and not full resource names like some other Google APIs).

Resource IDs

Google Ads entities (customers, campaigns, etc.) are referred to by their resource names throughout the API. However, it's important to note that the resource names themselves may have unique numerical resource IDs that identify each object in the hierarchy. In these cases, it may be useful to parse the resource name to extract these resource IDs and assemble a new one.

For example, examine the AdGroupAd resource name from the previous table:

customers/1234567890/adGroupAds/54321098765~2109876543210

This can be broken down into its individual resource IDs (separated by collection IDs) as follows:

Resource name components
Resource IDs	customer ID: "1234567890" ad group ID: "54321098765" ad group ad ID: "2109876543210"
Collection IDs	"customers" "adGroupAds"

Parsing the individual IDs lets you derive new resource names to reference the ad group ad's customer (customers/1234567890) or its ad group (customers/1234567890/adGroupAds/54321098765).

Key Point: Resource names in JSON request and response bodies are referred to by the resourceName field, not the name field like in some other Google Cloud APIs. Many Google Ads entities have name attributes themselves (campaign.Name, adGroup.Name, etc.), so resourceName is used to avoid collision with existing object names.

Identifiers of shared objects

Most objects in the API are associated with a single specific Google Ads customer. However, there are some object types that can be shared between multiple accounts. In practice, these are things like negative keyword lists or cross-account conversion actions that are usually created by managers and then shared with many client accounts.

The resource names of objects like these will differ, depending on which account you're sending an API call to.

Example: Cross-account conversion actions

Assume we have manager account 987-654-3210 that shares a cross-account conversion action with one of its client customer accounts 123-456-7890:

Making an API call to the manager account to, for example, update the conversion action's lookback window would reference the shared object using resource name: customers/9876543210/conversionActions/257733534.

Making an API call to the client account to opt-in to using the shared conversion action would reference it using resource name: customers/1234567890/conversionActions/257733534.

This is the same underlying conversion action, but its resource name is relative to the account used to access it.