## 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`](https://github.com/googleapis/googleapis/tree/HEAD/google/ads/googleads/v26/resources/customer.proto)
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` |

> [!IMPORTANT]
> **Key Point:** Google Ads API uses [*relative* resource names](https://cloud.google.com/apis/design/resource_names#relative_resource_name) (and not [*full* resource names](https://cloud.google.com/apis/design/resource_names#full_resource_name) 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](https://cloud.google.com/apis/design/resource_names#resource_id) 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](https://cloud.google.com/apis/design/resource_names#collection_id))
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`).

> [!IMPORTANT]
> **Key Point:** Resource names in JSON request and response bodies are referred to by the `resourceName` field, not the [`name`](https://cloud.google.com/apis/design/resource_names#q_why_is_the_special_field_called_name_instead_of_id) 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](https://support.google.com/google-ads/answer/7519927) or [cross-account
conversion actions](https://support.google.com/google-ads/answer/3030657) 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`:

![Diagram showing relationship of resource names to account hierarchies.](https://developers.google.com/static/google-ads/api/images/shared-resource-names.png)

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.