Getting Started

This guide takes you from zero to your first successful API response.

1. Get an API key

API keys are created by a partner admin in the TDC portal:

1. Sign in to the portal and open Settings → API Keys.
2. Click Create key, give it a descriptive label (e.g. production-storefront), and confirm.
3. Copy the key immediately. It looks like dk_live_... and is shown only once — it is stored hashed and cannot be retrieved later. If you lose it, revoke it and create a new one.

Your key is scoped to your partner account, so it can only ever read your own products.

Keep your key secret

Treat the key like a password. Use it only from your server — never embed it in browser JavaScript, a mobile app, or a public repository. See Authentication for details.

2. Make your first request

Request a product by its Desire Company ID. Replace dk_live_your_key_here with your key and 123 with a real product ID.

curl

curl https://api.prod.thedesirecompany.com/api/v1/public/products/123 \
  -H "Authorization: Bearer dk_live_your_key_here"

Node.js

const res = await fetch(
  'https://api.prod.thedesirecompany.com/api/v1/public/products/123',
  { headers: { Authorization: `Bearer ${process.env.TDC_API_KEY}` } },
);

if (!res.ok) throw new Error(`TDC API error: ${res.status}`);
const { data } = await res.json();
console.log(data.product.title);

3. Read the response

A successful request returns HTTP 200 with a data object:

{
  "data": {
    "status": "active",
    "product": {
      "id": 9066,
      "title": "Hellmann's Purely 100% Avocado Oil Mayonnaise",
      "description": "A real mayonnaise made with 100% avocado oil…",
      "short_description": "Avocado Oil Mayo made with a squeeze of lime and a pinch of black pepper.",
      "image": "https://cdn.thedesirecompany.com/images/hellmanns-avocado-oil-mayo.avif",
      "what_text": "What it is…",
      "who_text": "Who it's for…",
      "why_text": "Why it matters…",
      "videos": [
        {
          "id": 3557,
          "name": "Sam's Club In-Store Digital Signage",
          "aspect_ratio": "16x9",
          "length": 20.02
        }
      ],
      "pdp_urls": [
        {
          "id": 412,
          "pdp_url": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
          "video_file_url": "https://cdn.thedesirecompany.com/videos/hellmanns-avocado-mayo-16x9.mp4",
          "retailer": "Sam's Club",
          "skus": ["HELL-AVO-32"],
          "json_ld": {
            "@context": "https://schema.org",
            "@type": "VideoObject",
            "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
            "name": "Hellmann's 100% Avocado Oil Mayonnaise at Sam's Club",
            "transcript": "Hellmann's purely 100% Avocado Oil Mayonnaise brings flavor to everyday meals…",
            "creator": { "@type": "Person", "name": "Alexandra Caspero", "jobTitle": "CEO/Founder - Wellness Expert - Dietician" },
            "publisher": { "@type": "Organization", "name": "Hellmann's" },
            "about": { "@type": "Product", "brand": { "@type": "Brand", "name": "Hellmann's" } }
          }
        }
      ]
    }
  }
}

Map the text fields into your PDP template, then find the pdp_urls entry whose pdp_url matches the page you're rendering and inject its json_ld (or, when the page carries several of the product's videos, each videos[].json_ld) as a <script type="application/ld+json"> block for video rich results. Each entry's JSON-LD is anchored to its own retailer page URL. The what_text / who_text / why_text fields are expert-written copy you can surface as-is. See Embedding the JSON-LD for a copy-paste example.

Looking up by your own SKU

If you key your catalog by SKU rather than TDC's product ID, use the SKU endpoint instead — it takes your SKU string and is scoped to your partner account the same way:

curl https://api.prod.thedesirecompany.com/api/v1/public/sku/ABC123 \
  -H "X-API-Key: dk_live_your_key_here"

SKUs are registered against the individual retailer page that sells them — you can see which ones a page carries in its skus array — so the SKU endpoint returns only the pages carrying the SKU you asked for. That is usually what you want when rendering one page. If you need every page for the product, take the id from the response and call Get Product by ID.

Next steps

• Authentication — both header styles, scoping, rate limits, rotation.
• Get Product by SKU and Get Product by ID — full schemas.
• Errors — every error code and how to handle it.