This guide describes the common structure of all API calls. If you're using a client library to interact with the API, you won't need to know the underlying request details. However, some knowledge about the API call structure can come in handy when testing and debugging. Google Ads API is a [gRPC API](https://grpc.io/docs/guides/), with REST bindings. This means that there are two ways of making calls to the API. **Preferred**: 1. Create the body of the request as a [protocol buffer](https://developers.google.com/protocol-buffers). 2. Send it to the server using [HTTP/2](https://http2.github.io/). 3. Deserialize the response to a protocol buffer. 4. Interpret the results. Most of our documentation describes [using gRPC](https://developers.google.com/google-ads/api/reference/rpc/v26). **Optional**: 1. Create the body of the request as a [JSON](https://www.json.org/) object. 2. Send it to the server using HTTP 1.1. 3. Deserialize the response as a JSON object. 4. Interpret the results. Refer to the [REST interface](https://developers.google.com/google-ads/api/rest/overview) guide for more information on using REST. > [!NOTE] > **Note:** This guide describes the structure and transport headers common to both gRPC and REST protocols. ## Resource identifiers Objects in the Google Ads API are addressed using structured resource names and composite identifiers. ### Resource names Most objects in the API are identified by their resource name strings. These strings also serve as URLs when using the REST interface. See the REST interface [Resource names](https://developers.google.com/google-ads/api/rest/design/resource-names) for their structure. > [!IMPORTANT] > **Key Point:** Check out the [resources documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/overview#resources) for all supported resources and their path representation (`resource_name`). The same format is used for other services. ### Composite IDs If the ID of an object is not globally unique, a composite ID for that object is constructed by prepending its parent ID and a tilde (`~`). For example, an `AdGroupAd` has the resource name pattern `customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}`. Because its composite identifier combines the parent ad group ID (`ad_group.id`) and the underlying ad ID (`ad_group_ad.ad.id`), we prepend the ad group ID to the ad ID: - `AdGroupId` of **`123`** + `~` + `AdId` of **`45678`** = composite ad group ad ID of **`123~45678`**. > [!NOTE] > **Note:** Sharing an `AdId` across multiple ad groups is prohibited. Creating a new `AdGroupAd` that references an existing `AdId` in another ad group fails with `AdGroupAdError.AD_SHARING_NOT_ALLOWED`. ## Request headers These are the HTTP headers (or [gRPC metadata](https://grpc.io/docs/what-is-grpc/core-concepts/#metadata)) that accompany the body in the request: ### Authorization You must include an OAuth 2.0 access token in the form of `Authorization: Bearer YOUR_ACCESS_TOKEN` that identifies either a manager account acting on behalf of a client, or an advertiser directly managing their own account. Directions for retrieving an access token can be found in the [OAuth2 guide](https://developers.google.com/google-ads/api/docs/oauth/overview). An access token is valid for an hour after you acquire it; when it expires, refresh the access token to retrieve a new one. Note that our client libraries automatically refresh expired tokens. If you encounter authorization errors, ensure you are using the correct credentials and have sufficient permissions. A `USER_PERMISSION_DENIED` error indicates that the authenticated user may not have access to the customer account specified in the request. If your Google Cloud project is approved only for `Test` access and you send a request targeting a production account, the API returns `AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION` in v25 and later (or `AuthorizationError.ACTION_NOT_PERMITTED` in v24 and earlier). Refer to [Google Ads access levels](https://support.google.com/google-ads/answer/9978556) for details on managing permissions. ### login-customer-id This is the customer ID of the authorized customer to use in the request, without hyphens (`-`). If your access to the customer account is through a manager account, this header is *required* and must be set to the customer ID of the manager account. If you fail to include `login-customer-id` when you authenticate through a manager account, this results in an `AuthorizationError.USER_PERMISSION_DENIED` error. Review [common errors](https://developers.google.com/google-ads/api/docs/common-errors#authorizationerror) for more information on this error type. For a detailed explanation of how account access is resolved, refer to the [OAuth access model](https://developers.google.com/google-ads/api/docs/oauth/access-model) guide. > [!IMPORTANT] > **Key Term:** The **operating customer** is the customer ID in the request payload. For example, the operating customer in the following [`CampaignBudgetService`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignBudgetService) request is `1234567890`: ``` https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate ``` Setting the `login-customer-id` is equivalent to choosing an account in the Google Ads UI after signing in or clicking on your profile image at the top right. If you don't include this header, it defaults to the **operating customer**. > [!NOTE] > **Note:** You can retrieve the list of accounts that are *directly* accessible with your OAuth credentials by issuing a [`CustomerService.ListAccessibleCustomers`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerService/ListAccessibleCustomers) request. The `login-customer-id` is not required for this request type, and has no effect on the list of customers returned. ### linked-customer-id This header is required and used by partners (such as third-party app analytics providers or data partners) when acting on a linked Google Ads account. This header must specify the customer ID of the Google Ads account that has the [product link](https://developers.google.com/google-ads/api/docs/account-management/linking-product-accounts). Consider the scenario where a partner needs to make API calls to a Google Ads account based on a product link. - **Advertiser** : The Google Ads account being managed or updated by the API call. The ID of the Advertiser account is specified in the request. In REST, this is the `customerId` path parameter (for example, `customers/1111111111/...`), and in gRPC, this is the `customer_id` field in the request. - **Partner**: The partner account (for example, a third-party app analytics provider or data partner). - **Linked account** : The Google Ads account that has an established [product link](https://developers.google.com/google-ads/api/docs/account-management/linking-product-accounts) with Partner, granting Partner access to Advertiser. A user who has access to the **Partner** account makes API calls to act on entities in the **Advertiser** account (for example, to upload conversions or manage user lists). The **Linked account** can be the **Advertiser** account itself, or a manager account of the **Advertiser** account. The request headers must be set as follows: - **`Authorization`**: An OAuth 2.0 access token for a user who has access to Partner. - **`login-customer-id`** : The customer ID of the **Partner** account. The authenticated user must have access to this account. - **`linked-customer-id`** : The customer ID of the **Linked account**. This header signals that the authorization for this request relies on Linked account's product link with Partner. There are two linking scenarios: - If the **Advertiser** account has a direct product link with the **Partner** account, then the **Linked account** is **Advertiser** , and `linked-customer-id` must be set to the **Advertiser** account's customer ID. - If the **Advertiser** account is managed by a manager account that has a product link with the **Partner** account, then the **Linked account** is the manager account, and `linked-customer-id` must be set to the manager's customer ID. **Example 1: Direct link** If the Advertiser account `1111111111` has a direct link with the Partner account `2222222222`, and the API call is targeting `customers/1111111111/...`: Authorization: Bearer YOUR_ACCESS_TOKEN login-customer-id: 2222222222 linked-customer-id: 1111111111 **Example 2: Manager link** If the Advertiser account `1111111111` is managed by the manager account `3333333333`, the manager account `3333333333` has a link with the Partner account `2222222222`, and the API call is targeting `customers/1111111111/...`: Authorization: Bearer YOUR_ACCESS_TOKEN login-customer-id: 2222222222 linked-customer-id: 3333333333 ## Response headers The following headers (or [gRPC trailing-metadata](https://grpc.io/docs/what-is-grpc/core-concepts/#metadata)) are returned with the response body. We recommend that you log these values for debugging purposes. ### request-id The `request-id` is a string that uniquely identifies this request. Provide this value when contacting support to help troubleshoot failed or unexpected API requests.