Tailored Audience Permissions

Tailored Audience Permissions

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

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

Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_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

tailored_audience_id
required

A reference to the tailored 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

tailored_audience_permission_ids
optional

Scope the response to just the desired tailored 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/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "tailored_audience_id": "1nmth"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tailored_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/tailored_audiences/:tailored_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 tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored 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/5/accounts/:account_id/tailored_audiences/:tailored_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 tailored audience permissions for.

Type: string

Example: 18ce54aymz3

permission_level
required

The type of access to the tailored audience that the granted_account_id should have.

Type: enum

Possible values: READ_ONLY, READ_WRITE

tailored_audience_id
required

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

Type: string

Example: 2906h

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_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",
      "tailored_audience_id": "2906h"
    }
  },
  "data": {
    "tailored_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/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Revoke the specified Tailored Audience sharing permission.

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

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/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_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

tailored_audience_id
required

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

Type: string

Example: 1nmth

tailored_audience_permission_id
required

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

Type: string

Example: ri

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "tailored_audience_permission_id": "ri",
      "tailored_audience_id": "1nmth"
    }
  },
  "data": {
    "tailored_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
  }
}