Start with a property and a key

BOLD Embed is an API product. Ask BOLD to grant your account a property and configure the approved data origin before you start. Use an API key with embed:write scope and an API balance. A key does not grant access to another property.

The example below is a server-side integration. Replace the property, allowed website and data path with your own values. Never put your API key in a public page or in the embed snippet.

1. Return a card from your data endpoint

Serve this JSON from data/weekly-impact on the data origin configured for your property. Your server can calculate the value from your own database or another source you control. This example does not require a social account connection, Google Sheets or Zapier.

BOLD requests the source when rendering the card. If the endpoint fails or does not return a blocks array, it serves the last good card, or the initial spec supplied at creation. This is request-driven refresh, not a promise of continuous push updates in an already-open page.

{
  "blocks": [
    {
      "type": "stats",
      "items": [
        {
          "label": "Meals served",
          "value": "125"
        }
      ]
    }
  ]
}

2. Create the card from your server

POST to https://boldstudios.io/api/v1/embed/embeds with Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. Use the body below. Include an Idempotency-Key for a request you may retry; reuse it for an identical retry and choose a new key for a deliberate update.

To update this card later, call the same endpoint with the same property, kind and ref. It keeps the existing token instead of creating another card. Use the current API reference for pricing and response details.

{
  "property": "your-granted-property",
  "kind": "scorecard",
  "ref": "weekly-impact",
  "mode": "fetch",
  "source_path": "data/weekly-impact",
  "spec": {
    "blocks": [
      {
        "type": "stats",
        "items": [
          {
            "label": "Meals served",
            "value": "125"
          }
        ]
      }
    ]
  },
  "allowed_domains": [
    "www.example.org"
  ]
}

3. Install the card and check it

Replace RETURNED_TOKEN with the token from the response. Put the div where the card should appear and include the loader once on the page. A bare iframe URL is not supported. Your website must allow the loader script, and its hostname must match an allowed domain.

Change the value at your data endpoint, then reload the page and check the card. Test an endpoint failure too: the card should retain its last good values. The response also includes an image_url for a share image.

<div data-bold-embed="RETURNED_TOKEN"></div>
<script src="https://boldstudios.io/embed/embed.js" async></script>