> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pinnacle.sh/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server. # Create or Update a Brand POST https://api.pinnacle.sh/brands Content-Type: application/json 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](/api-reference/brands/submit). Reference: https://docs.pinnacle.sh/api-reference/brands/upsert ## Authentication - `PINNACLE-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects an upsertBrandSchema. - `address` (string, optional, nullable) — Primary brand address where the company is located. - `contact` (UpsertBrandSchemaContact, optional, nullable) — Contact information for the brand. - `dba` (string, optional, nullable) — "Doing Business As" name - the public name the brand operates under. - `description` (string, optional, nullable) — Brief description of what the brand does. - `ein` (string, optional, nullable) — Brand's Employer Identification Number (EIN) assigned by the IRS. - `email` (string, optional, nullable) — Main contact email address for the brand. - `id` (string, optional) — 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, nullable) — Legal name of the brand as registered. - `sector` (enum, optional, nullable) — Industry the brand operates in. - Allowed values: `AGRICULTURE`, `COMMUNICATION`, `CONSTRUCTION`, `EDUCATION`, `ENERGY`, `ENTERTAINMENT`, `FINANCIAL`, `GAMBLING`, `GOVERNMENT`, `HEALTHCARE`, `HOSPITALITY`, `INSURANCE`, `MANUFACTURING`, `NGO`, `REAL_ESTATE`, `RETAIL`, `TECHNOLOGY` - `type` (enum, optional, nullable) — Legal structure of the brand. - Allowed values: `GOVERNMENT`, `NON_PROFIT`, `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR` - `entityType` (enum, optional, nullable) — Legal entity type of the brand. - Allowed values: `LLC`, `SOLE_PROPRIETORSHIP`, `PARTNERSHIP`, `CORP`, `S_CORP` - `website` (string, optional, nullable) — Brand website URL. ## Response ### 200 Successfully create/updated the brand. - `createdAt` (string, required) — ISO 8601 formatted timestamp of when this brand was added to our system. - `id` (string, required) — The brand's ID. This identifier is a string that always begins with the prefix `b_`, for example: `b_1234567890`. - `isArchived` (boolean, required) — Indicates if this brand is archived. - `status` (enum, required) — 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. - Allowed values: `PENDING`, `UNVERIFIED`, `VERIFIED`, `VETTED`, `FAILED`, `INCOMPLETE` - `updatedAt` (string, required) — ISO 8601 formatted timestamp of when this brand was last updated. - `address` (string, optional) — Primary brand address where this brand is located. - `contact` (optionalContactSchema, optional) — Contact information for the primary brand representative. - `dba` (string, optional, nullable) — "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` (enum, optional) — Industry the Brand operates in. - Allowed values: `AGRICULTURE`, `COMMUNICATION`, `CONSTRUCTION`, `EDUCATION`, `ENERGY`, `ENTERTAINMENT`, `FINANCIAL`, `GAMBLING`, `GOVERNMENT`, `HEALTHCARE`, `HOSPITALITY`, `INSURANCE`, `MANUFACTURING`, `NGO`, `REAL_ESTATE`, `RETAIL`, `TECHNOLOGY` - `type` (enum, optional) — Legal structure of the brand. - Allowed values: `GOVERNMENT`, `NON_PROFIT`, `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR` - `entityType` (enum, optional) — Legal entity type of the brand. - Allowed values: `LLC`, `SOLE_PROPRIETORSHIP`, `PARTNERSHIP`, `CORP`, `S_CORP` - `website` (string, optional) — Brand website URL. ## Errors ### 400 Bad Request Error Validation failed. The payload has missing required fields and/or invalid types. See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information. - `description` (string, required) — Human-readable summary of validation failures. - `errors` (ZodErrorErrors, required) — 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 ### 401 Unauthorized Error 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. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 403 Forbidden Error 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. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 500 Internal Server Error An unexpected error occurred on Pinnacle's servers while processing your request. If this error persists, please contact support with the request details. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ## Types ### UpsertBrandSchemaContact Contact information for the brand. - `email` (string, optional, nullable) — Email address of the contact person. - `name` (string, optional, nullable) — Full name of the contact person. - `phone` (string, optional, nullable) — Phone number of the contact person in E.164 format. - `title` (string, optional, nullable) — Job title of the contact person. ### optionalContactSchema Contact information for the primary brand representative. - `email` (string, optional) — Email address of the contact person. - `name` (string, optional) — Full name of the contact person. - `phone` (string, optional) — Phone number of the contact person in E.164 format. - `title` (string, optional) — Job title or position oft he contact person. ### ZodErrorErrors 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 ## Examples **Request** ```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", "type": "PRIVATE_PROFIT", "entityType": "LLC", "website": "https://www.pinnacle.sh" } ``` **Response** ```json { "createdAt": "2024-09-11T19:41:12.099", "id": "b_1234567890", "isArchived": false, "status": "VERIFIED", "updatedAt": "2024-05-08T07:58:01.291", "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", "name": "Pinnacle", "sector": "TECHNOLOGY", "type": "PRIVATE_PROFIT", "entityType": "LLC", "website": "https://www.pinnacle.sh" } ``` **SDK Code** ```python Upserted Brand import requests url = "https://api.pinnacle.sh/brands" payload = { "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" } headers = { "PINNACLE-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Upserted Brand const url = 'https://api.pinnacle.sh/brands'; const options = { method: 'POST', headers: {'PINNACLE-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"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"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Upserted Brand package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/brands" payload := strings.NewReader("{\n \"address\": \"500 Folsom St, San Francisco, CA 94105\",\n \"contact\": {\n \"email\": \"michael.chen@trypinnacle.app\",\n \"name\": \"Michael Chen\",\n \"phone\": \"+14155551234\",\n \"title\": \"Customer Support Representative\"\n },\n \"dba\": \"Pinnacle RCS\",\n \"description\": \"A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.\",\n \"ein\": \"88-1234567\",\n \"email\": \"founders@trypinnacle.app\",\n \"id\": \"b_1234567890\",\n \"name\": \"Pinnacle\",\n \"sector\": \"TECHNOLOGY\",\n \"type\": \"PRIVATE_PROFIT\",\n \"entityType\": \"LLC\",\n \"website\": \"https://www.pinnacle.sh\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("PINNACLE-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Upserted Brand require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/brands") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["PINNACLE-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"address\": \"500 Folsom St, San Francisco, CA 94105\",\n \"contact\": {\n \"email\": \"michael.chen@trypinnacle.app\",\n \"name\": \"Michael Chen\",\n \"phone\": \"+14155551234\",\n \"title\": \"Customer Support Representative\"\n },\n \"dba\": \"Pinnacle RCS\",\n \"description\": \"A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.\",\n \"ein\": \"88-1234567\",\n \"email\": \"founders@trypinnacle.app\",\n \"id\": \"b_1234567890\",\n \"name\": \"Pinnacle\",\n \"sector\": \"TECHNOLOGY\",\n \"type\": \"PRIVATE_PROFIT\",\n \"entityType\": \"LLC\",\n \"website\": \"https://www.pinnacle.sh\"\n}" response = http.request(request) puts response.read_body ``` ```java Upserted Brand import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.pinnacle.sh/brands") .header("PINNACLE-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"address\": \"500 Folsom St, San Francisco, CA 94105\",\n \"contact\": {\n \"email\": \"michael.chen@trypinnacle.app\",\n \"name\": \"Michael Chen\",\n \"phone\": \"+14155551234\",\n \"title\": \"Customer Support Representative\"\n },\n \"dba\": \"Pinnacle RCS\",\n \"description\": \"A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.\",\n \"ein\": \"88-1234567\",\n \"email\": \"founders@trypinnacle.app\",\n \"id\": \"b_1234567890\",\n \"name\": \"Pinnacle\",\n \"sector\": \"TECHNOLOGY\",\n \"type\": \"PRIVATE_PROFIT\",\n \"entityType\": \"LLC\",\n \"website\": \"https://www.pinnacle.sh\"\n}") .asString(); ``` ```php Upserted Brand request('POST', 'https://api.pinnacle.sh/brands', [ 'body' => '{ "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" }', 'headers' => [ 'Content-Type' => 'application/json', 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Upserted Brand using RestSharp; var client = new RestClient("https://api.pinnacle.sh/brands"); var request = new RestRequest(Method.POST); request.AddHeader("PINNACLE-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"address\": \"500 Folsom St, San Francisco, CA 94105\",\n \"contact\": {\n \"email\": \"michael.chen@trypinnacle.app\",\n \"name\": \"Michael Chen\",\n \"phone\": \"+14155551234\",\n \"title\": \"Customer Support Representative\"\n },\n \"dba\": \"Pinnacle RCS\",\n \"description\": \"A developer-friendly, compliant API for SMS, MMS, and RCS, built to scale real conversations.\",\n \"ein\": \"88-1234567\",\n \"email\": \"founders@trypinnacle.app\",\n \"id\": \"b_1234567890\",\n \"name\": \"Pinnacle\",\n \"sector\": \"TECHNOLOGY\",\n \"type\": \"PRIVATE_PROFIT\",\n \"entityType\": \"LLC\",\n \"website\": \"https://www.pinnacle.sh\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Upserted Brand import Foundation let headers = [ "PINNACLE-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "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" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/brands")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```