## **🧭 Overview**

Brand Vault stores your agency's brand identity details, including the **Brand Voice Analysis** — a structured breakdown of your brand's tone, style, and messaging guidelines. If you need to retrieve this data programmatically (for example, to integrate it into your own workflows or tools), the Search Atlas API gives you direct access.

This article explains how to authenticate, find your Brand ID, and call the correct endpoint to retrieve Brand Voice Analysis data for any brand in your workspace, such as **creativeblue.agency**.



## **🔑 Step 1: Get Your API Key**

Before making any API calls, you need a valid Search Atlas API key.

1. Log in to your Search Atlas account.
2. Navigate to **Settings → API Keys**.
3. Copy your API key and store it securely. Treat it like a password — do not share it publicly.

## **🏷️ Step 2: Find Your Brand ID**

Every brand in Brand Vault has a unique **Brand ID**. You need this ID to query the correct brand's Voice Analysis.

1. Open **Brand Vault** from the header apps-grid icon → **More Features** → **Brand Vault**.
2. Select the brand you want to access (for example, **creativeblue.agency**).
3. Check the URL in your browser — the Brand ID appears as a unique identifier in the URL path (for example, `/brand-vault/brands/abc123xyz`).
4. Copy and save this ID for use in your API request.

Alternatively, you can list all brands in your workspace by calling the brands list endpoint and matching by brand name.



## **📡 Step 3: Call the Brand Voice Analysis Endpoint**

Once you have your API key and Brand ID, use the following request structure to retrieve the Brand Voice Analysis:

- **Method:** GET
- **Endpoint:**`/api/v1/brand-vault/brands/{brand_id}/voice-analysis`
- **Header:**`Authorization: Bearer YOUR_API_KEY`
- **Content-Type:**`application/json`

Replace **{brand\_id}** with the ID you copied in Step 2, and **YOUR\_API\_KEY** with your actual API key.



## **📦 Step 4: Understand the Response**

A successful response returns a JSON object containing the brand's voice analysis fields. Common fields include:

- **tone** — the overall tone of the brand (e.g., professional, conversational, authoritative)
- **style\_guidelines** — specific writing style rules for the brand
- **vocabulary** — preferred and avoided words or phrases
- **audience** — the target audience description
- **messaging\_pillars** — core themes and value propositions

You can use individual fields from this response to dynamically apply the brand voice in your own content pipelines or AI workflows.



## **⚙️ Using Dynamic Field-Based Preview**

The API supports **field-based filtering**, so you can request only the specific voice attributes you need rather than retrieving the entire analysis object. Append a `fields` query parameter to your request to specify which fields to return.

- Example: `?fields=tone,vocabulary,audience`
- This reduces payload size and speeds up integration, especially when embedding brand voice into real-time content generation tools.

## **⚠️ Common Issues and Fixes**

- **401 Unauthorized:** Your API key is missing or incorrect. Double-check it in Settings → API Keys.
- **404 Not Found:** The Brand ID is wrong or the brand has been deleted. Re-confirm the ID from Brand Vault.
- **403 Forbidden:** Your account role may not have API access enabled. Contact your workspace admin to verify permissions.
- **Empty voice analysis fields:** Brand Voice Analysis is generated after a brand profile is fully set up. Make sure the brand in Brand Vault has completed its onboarding and analysis steps.

## **💡 Best Practices**

- Store your API key as an environment variable — never hardcode it in your source code.
- Cache Brand Voice Analysis responses if you query the same brand frequently to avoid unnecessary API calls.
- Use the `fields` parameter to retrieve only what you need, keeping responses lightweight.
- If you manage multiple brands (like an agency), loop through your brands list endpoint to batch-retrieve voice data for all clients.

## **🙋 Need More Help?**

If you need further assistance, open the chat widget in the bottom-right corner of the platform and type **human teammate** to be connected with a member of our team.