The Google Ads API supports linking YouTube videos to your Google Ads account. This guide
explains how to use the API to add and remove links to your account.

## Link videos

Videos can be linked to your account in one of two ways, depending on who starts
the process, either:

1. You request that a video is linked to your account. In this scenario, you send a request to a creator, which they must accept in order to establish the link to their video. You can revoke a request that has been extended before it's accepted, and also remove a linked video after it's accepted.
2. The creator of the video requests that their video is linked to your Google Ads account. You can then choose to accept or reject their request.

The following methods are used in each scenario:

| Scenario | Action | Remarks |
| Scenario 1 | Get the video information from the YouTube API | Use the [YouTube API](https://developers.google.com/youtube/data/reference/rest/v3/channels/list) to get the `channel_id` to send the video link request to, and the `video_id` of the video you want to link. The `video_id` is the 11-character string found in YouTube video URLs (for example, the `v` parameter in `www.youtube.com/watch?v=VIDEO_ID` or the path in `youtu.be/VIDEO_ID`). |
| Scenario 1 |
| Scenario 1 |
| Scenario 1 |
| Scenario 1 |
|---|---|---|
| Create a link request | Use the [`DataLinkService.CreateDataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkService/CreateDataLink) method to create a link request, specifying both `youtube_video.channel_id` and `youtube_video.video_id` to identify the video and its associated channel. Starting in v24, you can also specify [`youtube_link_metadata.brand_channel_id`](https://developers.google.com/google-ads/api/reference/rpc/v26/YoutubeLinkMetadata#brand_channel_id) to provide the ID of the linked YouTube brand channel to help creators understand your brand. The [`status`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLink#status) of the [`DataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLink) shouldn't be set; the Google Ads API server will set this to `REQUESTED` upon the successful completion of the API call. |
| Inspect the status of a request | Use [`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream) or [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search) to query the [`data_link`](https://developers.google.com/google-ads/api/fields/v26/data_link) resource and inspect its [`status`](https://developers.google.com/google-ads/api/fields/v26/data_link#data_link.status). |
| Revoke a request | Use the [`DataLinkService.UpdateDataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkService/UpdateDataLink) method to revoke a link request by changing the [`status`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLink#status) of the [`DataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLink) from `REQUESTED` to `REVOKED`. |
| Remove a link | Use [`DataLinkService.RemoveDataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkService/RemoveDataLink) to remove a linked video. |
| Accept or reject a link request | Use the [`DataLinkService.UpdateDataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkService/UpdateDataLink) method to update the status of the [`DataLink`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLink) to `ENABLED` to accept or `REJECTED` to reject the request. |

## Retrieve link details

You can use [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search)
or
[`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream)
to query the [`data_link`](https://developers.google.com/google-ads/api/fields/v26/data_link) resource. The following query
retrieves details for YouTube video links, including the YouTube video ID and
channel ID:

    SELECT
      data_link.resource_name,
      data_link.status,
      data_link.youtube_video.video_id,
      data_link.youtube_video.channel_id
    FROM data_link
    WHERE data_link.type = 'VIDEO'

The following common errors can be thrown in this workflow:

| Error code | Explanation |
|---|---|
| [`DataLinkError.PERMISSION_DENIED`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkErrorEnum.DataLinkError#permission_denied) | The customer doesn't have the permission to perform this action. |
| [`DataLinkError.YOUTUBE_VIDEO_ID_INVALID`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkErrorEnum.DataLinkError#youtube_video_id_invalid) | A video link couldn't be created, since the video ID is invalid. |
| [`DataLinkError.INVALID_STATUS`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkErrorEnum.DataLinkError#invalid_status) | Thrown when the current status of the data link is invalid for the requested operation. |
| [`DataLinkError.INVALID_UPDATE_STATUS`](https://developers.google.com/google-ads/api/reference/rpc/v26/DataLinkErrorEnum.DataLinkError#invalid_update_status) | Thrown when attempting an unsupported status transition during an update (for example, moving directly from `REVOKED` to `ENABLED`). |
| [`MutateError.RESOURCE_ALREADY_EXISTS`](https://developers.google.com/google-ads/api/reference/rpc/v26/MutateErrorEnum.MutateError#resource_already_exists) | Thrown when a data link for the video already exists. |