Bulk Import Brands

Bulk Import Brands

Bulk Import Brands

Available on: Agency and Agency+ plans only

Import hundreds of brands at once using our Bulk Brand Import API. Perfect for agencies managing large client portfolios or publishers with extensive site networks.

---

Overview

The Bulk Brand Import API allows you to programmatically add multiple brands to your Cuppa account. Each imported brand automatically goes through our full Brand DNA pipeline, extracting brand voice, visual identity, and competitive intelligence.

Key Features:

• Import up to 100 brands per request

• CSV or JSON format supported

• Automatic Brand DNA extraction for each site

• Rate limited to 5 requests per minute

---

API Endpoint

POST https://app.cuppa.ai/api/brands/bulk-import

Authentication

Include your team API key in the request header:

X-API-KEY: your_team_api_key

To find your API key:

1. Go to Team Settings → API Keys

2. Copy your team API key

---

Request Formats

Option 1: JSON Array

Send a JSON body with an array of brand objects:

{
  "brands": [
    { "domain": "example.com", "name": "Example Company" },
    { "domain": "acme.org", "name": "Acme Corporation" },
    { "domain": "startup.io" }
  ]
}

Fields:

• domain (required): The website domain (e.g., "example.com")

• name (optional): Display name for the brand

Option 2: CSV Format

Send CSV content as a string:

{
  "csv": "domain,name\nexample.com,Example Company\nacme.org,Acme Corporation\nstartup.io,"
}

CSV Requirements:

• Must include a header row

• domain column is required

• name column is optional

---

Response

{
  "success": true,
  "total": 3,
  "queued": 3,
  "skipped": 0,
  "errors": [],
  "brands": [
    { "domain": "example.com", "siteId": "uuid-1", "status": "queued" },
    { "domain": "acme.org", "siteId": "uuid-2", "status": "queued" },
    { "domain": "startup.io", "siteId": "uuid-3", "status": "queued" }
  ]
}

Status Values:

• queued: Brand was created and Brand DNA extraction has started

• skipped: Domain already exists in your account

• error: Failed to import (see errors array for details)

---

Example: cURL

curl -X POST https://app.cuppa.ai/api/brands/bulk-import \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_team_api_key" \
  -d '{
    "brands": [
      { "domain": "client1.com", "name": "Client One" },
      { "domain": "client2.com", "name": "Client Two" }
    ]
  }'

---

Example: JavaScript/Node.js

const response = await fetch('https://app.cuppa.ai/api/brands/bulk-import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_team_api_key'
  },
  body: JSON.stringify({
    brands: [
      { domain: 'client1.com', name: 'Client One' },
      { domain: 'client2.com', name: 'Client Two' }
    ]
  })
});

const result = await response.json();
console.log(`Imported ${result.queued} brands`);

---

Example: Python

import requests

response = requests.post(
    'https://app.cuppa.ai/api/brands/bulk-import',
    headers={
        'Content-Type': 'application/json',
        'X-API-KEY': 'your_team_api_key'
    },
    json={
        'brands': [
            {'domain': 'client1.com', 'name': 'Client One'},
            {'domain': 'client2.com', 'name': 'Client Two'}
        ]
    }
)

result = response.json()
print(f"Imported {result['queued']} brands")

---

Limits & Considerations

Limit	Value
Max brands per request	100
Rate limit	5 requests per minute
Plan requirement	Agency or Agency+

Additional Notes:

• Duplicate domains are automatically skipped

• Each brand counts toward your plan's site limit

• Brand DNA extraction runs asynchronously (typically completes within 2-5 minutes)

• Invalid domain formats will be reported in the errors array

---

Error Handling

Common error responses:

Rate Limited (429)

{
  "success": false,
  "errors": [{ "domain": "", "error": "Rate limit exceeded. Try again in 1 minute." }]
}

Plan Not Supported (403)

{
  "success": false,
  "errors": [{ "domain": "", "error": "Bulk brand import is only available on Agency and Agency+ plans." }]
}

Site Limit Reached (403)

{
  "success": false,
  "errors": [{ "domain": "", "error": "You have reached your site limit (10). Please upgrade your plan or remove existing sites." }]
}

---

What Happens After Import

Once brands are imported:

1. Brand DNA Extraction begins automatically

   • Website scraping and analysis

   • Brand voice detection

   • Visual identity extraction (logos, colors, typography)

   • Competitive landscape research

2. Link Engine Indexing starts (if enabled)

   • Sitemap discovery

   • URL indexing for internal linking

3. Brand appears in your dashboard within seconds

   • Full Brand DNA data available within 2-5 minutes

---

Need Help?

• Documentation: learn.cuppa.ai

• Support: [email protected]

• Upgrade to Agency: cuppa.ai/pricing