# Create or Update a Brand

`POST /brands`

Create a new brand or update an existing one.

**To create a new brand:** Omit `id` — one will be generated automatically.

All fields are **required** except `description` and `dba`, and will be validated when submitted.

## Authentication

Send your API key in the `PINNACLE-API-KEY` header.

## Request body

Required.

Content type: `application/json`.

### Fields

- `address` — `string`, optional. Primary brand address where the company is located.
- `contact` — `object`, optional. Contact information for the brand.
- `contact.email` — `string`, optional. Email address of the contact person.
- `contact.name` — `string`, optional. Full name of the contact person.
- `contact.phone` — `string`, optional. Phone number of the contact person in E.164 format.
- `contact.title` — `string`, optional. Job title of the contact person.
- `dba` — `string`, optional. "Doing Business As" name - the public name the brand operates under.
- `description` — `string`, optional. Brief description of what the brand does.
- `ein` — `string`, optional. Brand's Employer Identification Number (EIN) assigned by the IRS.
- `email` — `string`, optional. Main contact email address for the brand.
- `id` — `string`, optional, minimum: 1. The unique identifier of the brand you want to update.

 This identifier is a string that always begins with the prefix `b_`, for example: `b_1234567890`.
- `name` — `string`, optional. Legal name of the brand as registered.
- `sector` — `object`, optional, values: `AGRICULTURE`, `COMMUNICATION`, `CONSTRUCTION`, `EDUCATION`, `ENERGY`, `ENTERTAINMENT`, `FINANCIAL`, `GAMBLING`, `GOVERNMENT`, `HEALTHCARE`, `HOSPITALITY`, `INSURANCE`, `MANUFACTURING`, `NGO`, `REAL_ESTATE`, `RETAIL`, `TECHNOLOGY`. Industry the brand operates in.
- `type` — `object`, optional, values: `GOVERNMENT`, `NON_PROFIT`, `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR`. Legal structure of the brand.
- `entityType` — `object`, optional, values: `LLC`, `SOLE_PROPRIETORSHIP`, `PARTNERSHIP`, `CORP`, `S_CORP`. Legal entity type of the brand.
- `website` — `string`, optional, format: url. Brand website URL.

### Example

```json
{
  "address": "500 Folsom St, San Francisco, CA 94105",
  "contact": {
    "email": "michael.chen@trypinnacle.app",
    "name": "Michael Chen",
    "phone": "+14155551234",
    "title": "Customer Support Representative"
  },
  "dba": "Pinnacle RCS",
  "description": "A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.",
  "ein": "88-1234567",
  "email": "founders@trypinnacle.app",
  "id": "b_1234567890",
  "name": "Pinnacle",
  "sector": "TECHNOLOGY",
  "entityType": "LLC",
  "type": "PRIVATE_PROFIT",
  "website": "https://www.pinnacle.sh"
}
```

## Responses

### 200

Successfully create/updated the brand.

Content type: `application/json`. Schema: `object`.

- `createdAt` — `string`. ISO 8601 formatted timestamp of when this brand was added to our system.
- `id` — `string`. The brand's ID. This identifier is a string that always begins with the prefix `b_`, for example: `b_1234567890`.
- `isArchived` — `boolean`. Indicates if this brand is archived.
- `status` — `BrandStatusEnum`, values: `PENDING`, `UNVERIFIED`, `VERIFIED`, `VETTED`, `FAILED`, `INCOMPLETE`. Current review status of the brand.

`INCOMPLETE`: Not submitted.

`IN REVIEW`: Being reviewed by carriers.

`VERIFIED`: Approved and ready to send messages.

`FAILED`: Issues and errors related to the campaign's details.

`VETTED`: Has undergone additional vetting by a third party service post the brand being verified. Your brand will be assigned a trust score, with higher trust scores having higher message volumes.

`UNVERIFIED`: Brand details have been updated, and the brand will need to undergo re-verification.
- `updatedAt` — `string`. ISO 8601 formatted timestamp of when this brand was last updated.
- `address` — `string`, optional. Primary brand address where this brand is located.
- `contact` — `OptionalContacts`, optional. Contact information for the primary brand representative.
- `contact.email` — `string`, optional. Email address of the contact person.
- `contact.name` — `string`, optional. Full name of the contact person.
- `contact.phone` — `string`, optional. Phone number of the contact person in E.164 format.
- `contact.title` — `string`, optional. Job title or position oft he contact person.
- `dba` — `string`, optional. "Doing Business As" name - the public name this brand operates under.
- `description` — `string`, optional. Brief description of what this brand does.
- `ein` — `string`, optional. Employer Identification Number (EIN) assigned by the IRS.
- `email` — `string`, optional. Main contact email address for this brand.
- `name` — `string`, optional. Legal name of the brand as registered.
- `sector` — `CompanySectorEnum`, optional, values: `AGRICULTURE`, `COMMUNICATION`, `CONSTRUCTION`, `EDUCATION`, `ENERGY`, `ENTERTAINMENT`, `FINANCIAL`, `GAMBLING`, `GOVERNMENT`, `HEALTHCARE`, `HOSPITALITY`, `INSURANCE`, `MANUFACTURING`, `NGO`, `REAL_ESTATE`, `RETAIL`, `TECHNOLOGY`. Industry the Brand operates in.
- `type` — `CompanyTypeEnum`, optional, values: `GOVERNMENT`, `NON_PROFIT`, `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR`. Legal structure of the brand.
- `entityType` — `CompanyEntityTypeEnum`, optional, values: `LLC`, `SOLE_PROPRIETORSHIP`, `PARTNERSHIP`, `CORP`, `S_CORP`. Legal entity type of the brand.
- `website` — `string`, optional. Brand website URL.

Example:

```json
{
  "id": "b_1234567890",
  "createdAt": "2024-09-11T19:41:12.099",
  "updatedAt": "2024-05-08T07:58:01.291",
  "isArchived": false,
  "status": "VERIFIED",
  "name": "Pinnacle",
  "dba": "Pinnacle RCS",
  "description": "A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.",
  "address": "500 Folsom St, San Francisco, CA 94105",
  "website": "https://www.pinnacle.sh",
  "sector": "TECHNOLOGY",
  "type": "PRIVATE_PROFIT",
  "entityType": "LLC",
  "ein": "88-1234567",
  "contact": {
    "name": "Michael Chen",
    "email": "michael.chen@trypinnacle.app",
    "phone": "+14155551234",
    "title": "Customer Support Representative"
  }
}
```

### 400

Validation failed. The payload has missing required fields and/or invalid types.

See https://zod.dev/error-formatting for more information.

Content type: `application/json`. Schema: `object`.

- `description` — `string`. Human-readable summary of validation failures.
- `errors` — `object`. Structured dictionary of issues containing two main sections:
- `errors`: Array of global validation errors not tied to specific fields
- `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

Example:

```json
{
  "description": "✖ Invalid input: expected string, received number\n  → at example_field",
  "errors": {
    "errors": [
      "Unrecognized key: 'extraKey'"
    ],
    "properties": {
      "example_field": {
        "errors": [
          "Invalid input: expected string, received NaN"
        ]
      }
    }
  }
}
```

### 401

The request lacks valid authentication credentials or the provided credentials are invalid.

Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Invalid API key."
}
```

### 403

Your subscription does not include access to this feature.

This occurs when attempting to use functionality that requires a higher subscription tier.
Please upgrade your subscription to access this feature.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Your subscription does not include access to this feature."
}
```

### 500

An unexpected error occurred on Pinnacle's servers while processing your request.

If this error persists, please contact support with the request details.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "An unexpected error occurred while processing your request."
}
```

## SDK examples

### TypeScript

```typescript
import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.brands.upsert({
    address: "500 Folsom St, San Francisco, CA 94105",
    contact: {
        email: "michael.chen@trypinnacle.app",
        name: "Michael Chen",
        phone: "+14155551234",
        title: "Customer Support Representative"
    },
    dba: "Pinnacle RCS",
    description: "A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.",
    ein: "88-1234567",
    email: "founders@trypinnacle.app",
    id: "b_1234567890",
    name: "Pinnacle",
    sector: "TECHNOLOGY",
    type: "PRIVATE_PROFIT",
    entityType: "LLC",
    website: "https://www.pinnacle.sh"
});
```

### Python

```python
import os
from rcs import Pinnacle
from rcs.brands import UpsertBrandSchemaContact

client = Pinnacle(
    api_key=os.environ["PINNACLE_API_KEY"],
)

client.brands.upsert(
    address="500 Folsom St, San Francisco, CA 94105",
    contact=UpsertBrandSchemaContact(
        email="michael.chen@trypinnacle.app",
        name="Michael Chen",
        phone="+14155551234",
        title="Customer Support Representative",
    ),
    dba="Pinnacle RCS",
    description="A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.",
    ein="88-1234567",
    email="founders@trypinnacle.app",
    id="b_1234567890",
    name="Pinnacle",
    sector="TECHNOLOGY",
    type="PRIVATE_PROFIT",
    entity_type="LLC",
    website="https://www.pinnacle.sh",
)
```

### Ruby

```ruby
require "rcs"

client = Pinnacle::Client.new(
  api_key: ENV.fetch("PINNACLE_API_KEY")
)

client.brands.upsert(
  address: "500 Folsom St, San Francisco, CA 94105",
  contact: {
    email: "michael.chen@trypinnacle.app",
    name: "Michael Chen",
    phone: "+14155551234",
    title: "Customer Support Representative"
  },
  dba: "Pinnacle RCS",
  description: "A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.",
  ein: "88-1234567",
  email: "founders@trypinnacle.app",
  id: "b_1234567890",
  name: "Pinnacle",
  sector: "TECHNOLOGY",
  type: "PRIVATE_PROFIT",
  entity_type: "LLC",
  website: "https://www.pinnacle.sh"
)
```

## Machine-readable schema

[OpenAPI 3.1 JSON](https://docs.pinnacle.sh/openapi.json)