Using the Public API to Manage Brand Voices

Overview

The Brand Voice API provides a set of tools for developers to automate the creation, management, and updating of brand voices for different locations within the CRM. This allows for integration with external software, automated client onboarding processes, and dynamic personalization of AI-generated content. By offering full create, read, update, and delete (CRUD) capabilities, the API helps agencies and developers scale their brand management efforts efficiently.

Key Benefits

Using the Brand Voice API offers several advantages for automating and scaling your operations.

• Automated Scaling: Programmatically create and manage brand voices across numerous locations without manual intervention.
• Flexible Setup: Generate a brand voice by providing details manually, supplying a website URL for analysis, or writing a descriptive text.
• Seamless Integration: Connect the CRM with external platforms, other CRMs, or automated onboarding systems.
• Centralized Control: Maintain a consistent brand tone, messaging, and audience targeting across all your tools.
• Dynamic Updates: Quickly update brand voice details as a business's identity evolves.

API Endpoints

The following endpoints are available for managing brand voices. All endpoints are relative to your API base URL and require the appropriate location ID.

List Brand Voices

GET /locations/:locationId/voices

Retrieves a list of all brand voices for a specified location. This endpoint supports pagination, search, and filtering, and can include deleted records.

Get a Specific Brand Voice

GET /locations/:locationId/voices/:brandVoiceId

Retrieves the complete details for a single, specific brand voice.

Create a Brand Voice

POST /locations/:locationId/voices

Creates a new brand voice for the location. You must specify one of the supported creation modes.

Update a Brand Voice

PATCH /locations/:locationId/voices/:brandVoiceId

Updates an existing brand voice. All fields in the request are optional; only the fields you provide will be modified.

Delete a Brand Voice

DELETE /locations/:locationId/voices/:brandVoiceId

Deletes the specified brand voice.

Set Default Brand Voice

POST /locations/:locationId/voices/:brandVoiceId/default

Sets a specific brand voice as the default for the location.

Brand Voice Creation Modes

You can create a brand voice using one of three distinct methods, depending on your needs and the information you have available.

Manual Mode

Use the manual mode for precise control. You directly supply all the necessary information, such as the brand name, tone of voice, target audience, and customer pain points.

URL Mode

Use the url mode for a quick, automated setup. Provide a website URL, and the CRM's AI will analyze the site's content to generate the brand voice details automatically.

Description Mode

Use the description mode when a website is not available. Provide a text description of the business, and the AI will generate the brand voice based on that information.

Validation Rules and Requirements

To ensure your API requests are successful, adhere to the following validation rules.

Required Fields

For all creation requests, the type field is mandatory and must be set to manual, url, or description.

When using the manual type, the following fields are also required:

• brandName
• toneOfVoice
• targetAudience
• customerPainPoints

Field Restrictions

• Do not include the manual input fields (like brandName) when using the url or description types.
• Do not include a URL field when using the manual type.

Update Behavior

When updating a brand voice with a PATCH request, all fields are optional. The API will only modify the specific fields included in your request.

Frequently Asked Questions

When should I use manual mode versus an AI-generated mode?

Choose manual mode when you need exact control over every aspect of the brand voice. The URL and description modes are best for rapid, automated setup based on existing information.

Can I update just one field of a brand voice?

Yes. The PATCH endpoint allows for partial updates. You only need to send the field you wish to change.

What happens if I send incorrect fields for a creation mode?

The API will return a validation error if the fields provided do not match the requirements of the selected creation type.

Can a location have multiple brand voices?

Yes, you can create and manage multiple brand voices for a single location and designate one as the default.

Can I recover a deleted brand voice?

Depending on system configuration, deleted brand voices might be retrievable. It is recommended to confirm this behavior before proceeding with a deletion.

Do brand voices created via the API work with AI features like Content AI?

Yes, brand voices created through the API are fully compatible with the CRM's AI-powered features, including Content AI and Agent Studio.