Audience Segment Sharing Policies

Sharing policies can be used to share access to an audience segment with ad accounts within the same Organization, or with ad accounts in another Organization. To revoke the access the sharing policy can be deleted.

Audience segments differ from other shareable resources such as pixels and mobile apps. A shared audience segment is always scoped to the specific ad account it was shared to. The recipient organization cannot re-share a received audience with other ad accounts within their organization or across organizations, and cannot use a received cross-org audience to create lookalike audiences.

Attributes

sharing_policy entity

Attribute	Description	Required	Possible values
sharing_policy_id	id of the sharing_policy entity	-	Read-only attribute
source	audience segment to be shared	R	see source attribute
target	entity that the audience segment should be shared with	R	see target attribute
parent_policy_id	used when sharing an audience segment with an ad account in an Organization outside of the owning Organization	O

source attribute

Attribute	Description	Required	Possible values
resource_id	the id of the resource	R	id of the audience segment
resource_type	the type of the resource	R	segments

target attribute

Attribute	Description	Required	Possible values
resource_id	the id of the entity	R	id of the entity that the segment is to be shared with
resource_type	the type of the entity	R	adaccounts,organizations

This request will list all sharing policies where the given audience segment is the source, including both in-org and cross-org policies.

A target.resource_type of organizations indicates a cross-org parent policy — the audience segment is shared with an external Organization. A target.resource_type of adaccounts with a parent_policy_id is a cross-org child policy — the audience segment is shared with an ad account within an external Organization. A target.resource_type of adaccounts without a parent_policy_id is an in-org policy — the audience segment is shared with an ad account within the same Organization.

Authorization: Requires access to the audience segment's owning organization. Callers without access receive a 403.

HTTP Request

GET
https://businessapi.snapchat.com/v1/segments/{segment_id}/sharing_policies

Request Parameters

Parameter	Default	Description
segment_id		UUID of the audience segment
limit	10	Maximum number of policies per page
cursor		Opaque pagination cursor returned in `paging.next_page_id`

HTTP Response

Field	Description
request_id	UUID of the request
request_status	`SUCCESS` or `ERROR`
sharing_policies	list of sharing_policy objects. See the sharing_policy entity above.
paging	pagination info. Follow `next_page_id` to retrieve all policies when the response spans pages.

Note: role_type_names and timestamp are not returned by this endpoint. Use GET /v1/sharing_policies/{sharing_policy_id} to retrieve full policy details.

Example request

This request fetches all sharing policies for audience segment a1b2c3d4-0000-0000-0000-000000000001.

curl \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    'https://businessapi.snapchat.com/v1/segments/a1b2c3d4-0000-0000-0000-000000000001/sharing_policies'

Example response

{
  "request_id": "e3f7a1c2-0000-0000-0000-000000000099",
  "request_status": "SUCCESS",
  "sharing_policies": [
    {
      "sharing_policy_id": "f0000001-0000-0000-0000-000000000001",
      "source": {
        "resource_type": "segments",
        "resource_id": "a1b2c3d4-0000-0000-0000-000000000001"
      },
      "target": {
        "resource_type": "organizations",
        "resource_id": "b2c3d4e5-0000-0000-0000-000000000002"
      }
    },
    {
      "sharing_policy_id": "f0000002-0000-0000-0000-000000000002",
      "source": {
        "resource_type": "segments",
        "resource_id": "a1b2c3d4-0000-0000-0000-000000000001"
      },
      "target": {
        "resource_type": "adaccounts",
        "resource_id": "c3d4e5f6-0000-0000-0000-000000000003"
      },
      "parent_policy_id": "f0000001-0000-0000-0000-000000000001"
    },
    {
      "sharing_policy_id": "f0000003-0000-0000-0000-000000000003",
      "source": {
        "resource_type": "segments",
        "resource_id": "a1b2c3d4-0000-0000-0000-000000000001"
      },
      "target": {
        "resource_type": "adaccounts",
        "resource_id": "d4e5f6a7-0000-0000-0000-000000000004"
      }
    }
  ],
  "paging": {
    "next_page_id": ""
  }
}

In this example:

f0000001 is a cross-org parent policy — the audience segment is shared with an external organization.
f0000002 is a cross-org child policy — the audience segment is shared with an ad account in that external organization (parent_policy_id links back to f0000001).
f0000003 is an in-org policy — the audience segment is shared with an ad account in the owning organization.

HTTP Request

POST
https://businessapi.snapchat.com/v1/segments/{segment_id}/sharing_policies

Request Parameters

Parameter	Default	Description
segment_id		the id of the segment

Body Parameters

Parameter	Default	Description
sharing_policies		the sharing_policies needs to include a source attribute specifying the audience segment and a target attribute specifying the ad account to share it with

Example request

This request shares audience segment a1b2c3d4-0000-0000-0000-000000000001 with an ad account within the same Organization.

curl -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    'https://businessapi.snapchat.com/v1/segments/a1b2c3d4-0000-0000-0000-000000000001/sharing_policies' \
    -D '{
          "sharing_policies": [
            {
              "source": {
                "resource_id": "a1b2c3d4-0000-0000-0000-000000000001",
                "resource_type": "segments"
              },
              "target": {
                "resource_id": "d4e5f6a7-0000-0000-0000-000000000004",
                "resource_type": "adaccounts"
              }
            }
          ]
        }'

Example response

{
  "request_id": "eb0bf046-5eb9-42e7-99fd-234994d66ce4",
  "request_status": "SUCCESS",
  "sharing_policies": [
    {
      "sub_request_status": "SUCCESS",
      "sharing_policy": {
        "sharing_policy_id": "f0000003-0000-0000-0000-000000000003",
        "source": {
          "resource_type": "segments",
          "resource_id": "a1b2c3d4-0000-0000-0000-000000000001"
        },
        "target": {
          "resource_type": "adaccounts",
          "resource_id": "d4e5f6a7-0000-0000-0000-000000000004"
        }
      }
    }
  ]
}

To create a sharing policy with an external Organization you will need to carry out an API request specifying the audience segment to be shared and the Organization it is to be shared with. If the request is successful it will return a sharing_policy_id.

The sharing_policy_id should be stored as it is required to be passed as parent_policy_id once you execute an API request to share the audience segment with an ad account in the external Organization.

HTTP Request

POST
https://businessapi.snapchat.com/v1/segments/{segment_id}/sharing_policies

Request Parameters

Parameter	Default	Description
segment_id		the id of the segment

Body Parameters

Parameter	Default	Description
sharing_policies		the sharing_policies needs to include a source attribute specifying the audience segment to be shared and a target attribute specifying the external Organization

Example Request

This request creates a sharing policy for audience segment a1b2c3d4-0000-0000-0000-000000000001 to be shared with the external Organization b2c3d4e5-0000-0000-0000-000000000002. Note how the response passes back a sharing_policy_id.

curl -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    'https://businessapi.snapchat.com/v1/segments/a1b2c3d4-0000-0000-0000-000000000001/sharing_policies' \
    -D '{
          "sharing_policies": [
            {
              "source": {
                "resource_id": "a1b2c3d4-0000-0000-0000-000000000001",
                "resource_type": "segments"
              },
              "target": {
                "resource_id": "b2c3d4e5-0000-0000-0000-000000000002",
                "resource_type": "organizations"
              }
            }
          ]
        }'

Example Response

A sharing_policy_id is returned by the API response.

{
  "request_id": "b08b5c1d-b602-44a1-a6f7-b7f796545993",
  "request_status": "SUCCESS",
  "sharing_policies": [
    {
      "sub_request_status": "SUCCESS",
      "sharing_policy": {
        "sharing_policy_id": "f0000001-0000-0000-0000-000000000001",
        "source": {
          "resource_type": "segments",
          "resource_id": "a1b2c3d4-0000-0000-0000-000000000001"
        },
        "target": {
          "resource_type": "organizations",
          "resource_id": "b2c3d4e5-0000-0000-0000-000000000002"
        }
      }
    }
  ]
}

Before an audience segment can be shared with an ad account in an external Organization, the segment must first be shared with that external Organization. Once the segment has been shared with the external Organization, the sharing_policy_id of that request must be stored and passed as parent_policy_id when sharing the segment with a specific ad account in the external Organization.

HTTP Request

POST
https://businessapi.snapchat.com/v1/segments/{segment_id}/sharing_policies

Request Parameters

Parameter	Default	Description
segment_id		the id of the segment

Body Parameters

Parameter	Default	Description
parent_policy_id		the sharing_policy_id established when the audience segment was shared to the external Organization
sharing_policies		the sharing_policies needs to include a source attribute specifying the audience segment and a target attribute specifying the ad account in the external Organization to share it with

Example Request

The following request shares audience segment a1b2c3d4-0000-0000-0000-000000000001 with ad account c3d4e5f6-0000-0000-0000-000000000003 in the external Organization. The parent_policy_id references the sharing_policy_id created when the segment was shared with the Organization.

curl -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    'https://businessapi.snapchat.com/v1/segments/a1b2c3d4-0000-0000-0000-000000000001/sharing_policies' \
    -D '{
          "parent_policy_id": "f0000001-0000-0000-0000-000000000001",
          "sharing_policies": [
            {
              "source": {
                "resource_id": "a1b2c3d4-0000-0000-0000-000000000001",
                "resource_type": "segments"
              },
              "target": {
                "resource_id": "c3d4e5f6-0000-0000-0000-000000000003",
                "resource_type": "adaccounts"
              }
            }
          ]
        }'

Example Response

{
  "request_id": "c55e31db-bcd3-46b9-aa65-76cdd993a370",
  "request_status": "SUCCESS",
  "sharing_policies": [
    {
      "sub_request_status": "SUCCESS",
      "sharing_policy": {
        "sharing_policy_id": "f0000002-0000-0000-0000-000000000002",
        "source": {
          "resource_type": "segments",
          "resource_id": "a1b2c3d4-0000-0000-0000-000000000001"
        },
        "target": {
          "resource_type": "adaccounts",
          "resource_id": "c3d4e5f6-0000-0000-0000-000000000003"
        },
        "parent_policy_id": "f0000001-0000-0000-0000-000000000001"
      }
    }
  ]
}

Deleting a sharing policy means the audience segment will become inaccessible to the target ad account or organization. To fully revoke cross-org access, delete the child policy first, then delete the parent policy.

HTTP Request

DELETE
https://businessapi.snapchat.com/v1/sharing_policies/{sharing_policy_id}

Request Parameters

Parameter	Default	Description
sharing_policy_id		the id of the sharing policy to be deleted

Example Request

This request deletes sharing policy id f0000002-0000-0000-0000-000000000002.

curl -X DELETE \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    'https://businessapi.snapchat.com/v1/sharing_policies/f0000002-0000-0000-0000-000000000002'

Example response

{
  "request_id": "6c8015bb-ec37-4079-9581-6a0b324088d5",
  "request_status": "SUCCESS"
}

Was this page helpful?

Yes

List Sharing Policies by Audience Segment​

Create Sharing Policies for Ad Accounts in the Same Organization​

Create Sharing Policies for an External Organization​

Create Sharing Policies for an Ad Account in an External Organization​

Delete a Sharing Policy​

List Sharing Policies by Audience Segment

Create Sharing Policies for Ad Accounts in the Same Organization

Create Sharing Policies for an External Organization

Create Sharing Policies for an Ad Account in an External Organization

Delete a Sharing Policy