> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link a Spotify show or Facebook Page to an advertiser

> Add the advertiser's Spotify show or Facebook Page when you connect its account, so podcast promotions use the right show and the advertiser's Page is on record.

When a [Spotify or Meta account connection](https://docs.apostra.com/v3/connection-account-discovery.md)
is connected and mapped to an advertiser, the connection can ask about the
advertiser's own show or Page:

* **Spotify:** the advertiser's Spotify show, for podcast promotion.
* **Meta:** the Facebook Page the advertiser advertises as.

Answer with `save_connection` and its `ownedLink` input. Answering is optional. The connection works whether you answer, skip the
question or confirm there is nothing to link. This is available to accounts
with Creative Engines access.

The connection does not list the Facebook Pages an ad account can promote. Any
buyer can list the Pages one product can run as with `search`, using
`kind: "wholesale_product"`, a `filter` with the `advertiserId`, the
`productId` and `resourceKind: "platform_identity"`, and
`include: ["executionResources"]`. Each result's `providerId` is a Page id,
with its `name` when Meta returns one. To use a Page on a buy, pass that id as
`products[].pageId` on `save_media_buy`.

## What the connection shows

Read the connection with `get(kind: "connection")`. For each mapped advertiser,
`ownedLinks` says whether a show or Page is available to link, already linked,
or confirmed absent.

```json theme={null}
{
  "ownedLinks": [
    {
      "advertiserId": "123",
      "platform": "spotify",
      "kind": "show",
      "state": "available",
      "question": "Does this advertiser have a Spotify show to promote?",
      "linked": []
    }
  ]
}
```

On a Meta connection, `candidateCount` is how many Facebook Pages Meta lets
the advertiser's mapped ad account promote. `linked` lists the Pages the
advertiser's brand profile names that are among them.

```json theme={null}
{
  "ownedLinks": [
    {
      "advertiserId": "123",
      "platform": "meta",
      "kind": "page",
      "state": "linked",
      "question": "Which Facebook Page does this advertiser advertise as?",
      "candidateCount": 3,
      "linked": [
        {
          "id": "104512345678901",
          "name": "Chalk Lines",
          "url": "https://www.facebook.com/chalklines"
        }
      ]
    }
  ]
}
```

Apostra reads the Pages from Meta each time you read the connection, with the
connection's own Meta access. If Meta cannot be read at that moment, the offer
leaves out `candidateCount` and `linked`, and the rest of the connection still
reads.

## Link a Spotify show

Pass the mapped advertiser, the existing Spotify connection, and the show URL.
Apostra checks the link with Spotify and saves the show as an `offering`
catalog item for that advertiser.

```json theme={null}
{
  "connectionId": "456",
  "ownedLink": {
    "state": "linked",
    "platform": "spotify",
    "kind": "show",
    "advertiserId": "123",
    "url": "https://open.spotify.com/show/6fS5boWGwYTShddG7SKlVw"
  }
}
```

The saved catalog item identifies the show for Spotify podcast promotion. Use
that offering with the promotion so Spotify receives the matching
`promotion_target_id`.

## Link a Facebook Page

Pass the mapped advertiser, the existing Meta connection, and the Page as
either its facebook.com link (`url`) or its username (`handle`). Give one, not
both.

```json theme={null}
{
  "connectionId": "789",
  "ownedLink": {
    "state": "linked",
    "platform": "meta",
    "kind": "page",
    "advertiserId": "123",
    "url": "https://www.facebook.com/chalklines"
  }
}
```

Apostra asks Meta which Pages the advertiser's mapped ad account may promote,
and links the Page only if it is exactly one of them. These forms work:

* `https://www.facebook.com/<username>`
* `https://www.facebook.com/<Page id>`
* `https://www.facebook.com/profile.php?id=<Page id>`
* a handle such as `chalklines` or `@chalklines`

The Page is saved as one of the advertiser's stated pages in its brand
profile (`brandProfile.stated.pages` on `save_advertiser`), with its link and
name. Apostra
does not store Meta's Page id. It matches the stated page against Meta's list
again every time the connection is read, so a Page the ad account loses access
to stops showing as linked.

A creative session for a Meta image post uses the linked Page when the request
names no `page_id`. The Page is checked against the same live list first. A
`page_id` in the request always wins, and must also be one of the Pages the ad
account can promote. If the profile names no Page the ad account can still
promote, or names more than one, the session leaves the Page unset and you
choose it as before.

The save is refused, and nothing changes, when:

* the link or handle names no Page the ad account can promote. Give the ad
  account access to the Page in Meta, or link a Page it already lists;
* the link or handle names more than one of those Pages. Link the Page by its
  `facebook.com/<Page id>` link instead; or
* the brand profile already names a different Page the ad account can promote.
  Confirm the advertiser has no Page, or remove that page with
  `save_advertiser`, then link the new one.

## Confirm there is nothing to link

If the advertiser has no Spotify show or no Facebook Page, save that fact
instead. The connection stops offering the question until one is linked
later.

```json theme={null}
{
  "connectionId": "456",
  "ownedLink": {
    "state": "absent",
    "platform": "spotify",
    "kind": "show",
    "advertiserId": "123"
  }
}
```

For Meta, use `"platform": "meta"` and `"kind": "page"`. Confirming that a
Spotify show is absent archives the advertiser's linked Spotify shows.
Confirming that a Facebook Page is absent removes the Facebook pages from the
advertiser's stated pages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.