# 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:

```json
{
  "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:

```json
{
  "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

```json
{
  "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

```bash
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

```javascript
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

```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)**

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

**Plan Not Supported (403)**

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

**Site Limit Reached (403)**

```json
{
  "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](https://learn.cuppa.ai)
* **Support**: <support@cuppa.ai>
* **Upgrade to Agency**: [cuppa.ai/pricing](https://cuppa.ai/pricing)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/brand-dna/bulk-import-brands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.