custom-audience-permissions

Custom Audience Permissions

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions¶

Retrieve details for some or all permissions associated with the specified custom audience.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
custom_audience_id required	A reference to the custom audience you are operating with in the request. Type: string Example: `1nmth`
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
granted_account_ids optional	Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `18ce54aymz3`
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	Scope the response to just the desired custom audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `ri`
with_total_count optional	Include the `total_count` response attribute. Note: This parameter and `cursor` are exclusive. Note: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request¶

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "custom_audience_id": "1nmth"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "custom_audience_id": "1nmth",
      "permission_level": "READ_ONLY",
      "id": "ri",
      "created_at": "2017-06-08T23:17:59Z",
      "granted_account_id": "18ce54aymz3",
      "updated_at": "2017-06-08T23:17:59Z",
      "deleted": false
    }
  ]
}

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions¶

Create a new permission object allowing the specified audience to be shared with a given account.

Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the is_owner response attribute in the response for a given audience.

Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS account feature.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
granted_account_id required	The account you wish to grant the custom audience permissions for. Type: string Example: `18ce54aymz3`
permission_level required	The type of access to the custom audience that the `granted_account_id` should have. Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
custom_audience_id required	A reference to the custom audience you are operating with in the request. Type: string Example: `2906h`

Example Request¶

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "granted_account_id": "18ce54aymz3",
      "permission_level": "READ_ONLY",
      "custom_audience_id": "2906h"
    }
  },
  "data": {
    "custom_audience_id": "2906h",
    "permission_level": "READ_ONLY",
    "id": "14m",
    "created_at": "2017-09-12T23:49:34Z",
    "granted_account_id": "18ce54aymz3",
    "updated_at": "2017-09-12T23:49:34Z",
    "deleted": false
  }
}

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id¶

Revoke the specified Custom Audience sharing permission.

When revoked, we guarantee that the granted account (granted_account_id) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Parameters¶

Name Description

account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

custom_audience_id
required

A reference to the custom audience you are operating with in the request.

Type: string

Example: 1nmth

custom_audience_permission_id
required

A reference to the custom audience permission you are operating with in the request.

Type: string

Example: ri

Example Request¶

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "custom_audience_permission_id": "ri",
      "custom_audience_id": "1nmth"
    }
  },
  "data": {
    "custom_audience_id": "1nmth",
    "permission_level": "READ_ONLY",
    "id": "ri",
    "created_at": "2017-06-08T23:17:59Z",
    "granted_account_id": "18ce54aymz3",
    "updated_at": "2017-08-30T18:29:35Z",
    "deleted": true
  }
}