> 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. # Get Toll-Free Campaign by ID GET https://api.pinnacle.sh/campaigns/toll-free/{campaignId} Retrieve Toll-Free campaign. Reference: https://docs.pinnacle.sh/api-reference/campaigns/toll-free/get ## Authentication - `PINNACLE-API-KEY` header (required) — API Key authentication via header ## Request ### Path parameters - `campaignId` (string, required) — Unique identifier of toll-free campaign. Must begin with the prefix `tf_`. ## Response ### 200 Successfully retrieved. - `brand` (ExtendedBrand, required) — Brand associated with this campaign. - `status` (enum, required) — Current review status of the brand. `INCOMPLETE`: Has not been submitted. `PENDING`: Currently being reviewed. `VERIFIED`: Verified and good to go. `VETTED`: Brand has been vetted by an external provider and has received vetting scores. - Allowed values: `INCOMPLETE`, `IN REVIEW`, `VERIFIED`, `FAILED` - `campaignId` (string, required) — Unique identifier for the campaign. Begins with the prefix `tf_`. - `keywords` (TollFreeWithExtendedBrandAndStatusKeywords, optional) — Keyword response configuration. - `links` (TollFreeWithExtendedBrandAndStatusLinks, optional) — Legal documentation links. - `monthlyVolume` (enum, optional) — Message volume. - Allowed values: `10`, `100`, `1,000`, `10,000`, `100,000`, `250,000`, `500,000`, `750,000`, `1,000,000`, `5,000,000`, `10,000,000+` - `name` (string, optional) — Display name of the campaign. - `optIn` (TollFreeWithExtendedBrandAndStatusOptIn, optional) — Opt-in keyword settings. - `options` (TollFreeWithExtendedBrandAndStatusOptions, optional) — Campaign configuration options. - `productionMessageContent` (string, optional) — Explain message that would be sent. - `useCase` (TollFreeWithExtendedBrandAndStatusUseCase, optional) — Use case classification for the campaign. ## 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. ### 404 Not Found Error The requested resource could not be found. This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it. - `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 ### ExtendedBrand - `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. ### TollFreeWithExtendedBrandAndStatusKeywords Keyword response configuration. - `HELP` (TollFreeWithExtendedBrandAndStatusKeywordsHelp, optional) — Help keyword settings. - `OPT_IN` (TollFreeWithExtendedBrandAndStatusKeywordsOptIn, optional) — Opt-in keyword settings. ### TollFreeWithExtendedBrandAndStatusLinks Legal documentation links. - `privacyPolicy` (string, optional) — Privacy policy URL. - `termsOfService` (string, optional) — Terms of service URL. ### TollFreeWithExtendedBrandAndStatusOptIn Opt-in keyword settings. - `method` (enum, optional) — Method used to collect opt-in consent from users. See the [Opt-In Methods and Workflow](/guides/campaigns/opt-in-compliance#opt-in-methods-and-workflow) section for detailed requirements. - `DIGITAL`: Web form, app, or online checkout. Requires URL to the form. Checkbox must not be pre-selected. - `PAPER`: Physical paper form (in-store, event, etc.). Requires URL/image of the form with SMS disclosures visible. - `TEXT`: Text-to-join keyword campaign. Users text a keyword to opt in. Requires the keyword and number. - `VERBAL`: In-person or phone consent. Not allowed for marketing campaigns. Requires script and confirmation SMS details. - Allowed values: `DIGITAL`, `PAPER`, `TEXT`, `VERBAL` - `url` (string, optional) — Url to opt in. - `workflowDescription` (string, optional) — Explain how users find the opt-in. ### TollFreeWithExtendedBrandAndStatusOptions Campaign configuration options. - `ageGated` (boolean, optional) — Whether the campaign is age-gated. ### TollFreeWithExtendedBrandAndStatusUseCase Use case classification for the campaign. - `summary` (string, optional) — Summary of the use case. - `value` (enum, optional) — The primary use case classification for this campaign. - Allowed values: `APP_NOTIFICATIONS`, `APPOINTMENTS`, `AUCTIONS`, `AUTO_REPAIR_SERVICES`, `BANK_TRANSFERS`, `BILLING`, `BOOKING_CONFIRMATIONS`, `BUSINESS_UPDATES`, `CAREER_TRAINING`, `CHATBOT`, `CONVERSATIONAL_ALERTS`, `COURIER_SERVICES_DELIVERIES`, `COVID_19_ALERTS`, `EMERGENCY_ALERTS`, `EVENTS_PLANNING`, `FINANCIAL_SERVICES`, `FRAUD_ALERTS`, `FUNDRAISING`, `GENERAL_MARKETING`, `GENERAL_SCHOOL_UPDATES`, `HEALTHCARE_ALERTS`, `HOUSING_COMMUNITY_UPDATES`, `HR_STAFFING`, `INSURANCE_SERVICES`, `JOB_DISPATCH`, `LEGAL_SERVICES`, `MIXED`, `MOTIVATIONAL_REMINDERS`, `NOTARY_NOTIFICATIONS`, `ORDER_NOTIFICATIONS`, `POLITICAL`, `PUBLIC_WORKS`, `REAL_ESTATE_SERVICES`, `RELIGIOUS_SERVICES`, `REPAIR_DIAGNOSTICS_ALERTS`, `REWARDS_PROGRAM`, `SURVEYS`, `SYSTEM_ALERTS`, `TWO_FA`, `VOTING_REMINDERS`, `WAITLIST_ALERTS`, `WEBINAR_REMINDERS`, `WORKSHOP_ALERTS` ### 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 ### 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. ### TollFreeWithExtendedBrandAndStatusKeywordsHelp Help keyword settings. - `message` (string, optional) — Message sent when a user sends HELP. Must include at least one support contact method (phone, email, or website). ### TollFreeWithExtendedBrandAndStatusKeywordsOptIn Opt-in keyword settings. - `message` (string, optional) — Message sent when a user opt-in. Must include brand name, confirmation of subscription, and disclosures (STOP and HELP instructions, message and data rates). - `keywords` (list of string, optional) — Keywords that trigger opt-in response. ## Examples **Response** ```json { "brand": { "createdAt": "2024-08-17T08:00:30.632", "id": "b_1234567890", "isArchived": false, "status": "VERIFIED", "updatedAt": "2024-12-09T10:03:54.934", "address": "500 Folsom Street, San Francisco, CA 94105", "contact": { "email": "janedoe1@pinnacle.example", "name": "Jane Doe", "phone": "+14155550123", "title": "Customer Support Specialist" }, "dba": "Pinnacle RCS", "ein": "12-3456789", "email": "founders@trypinnacle.app", "name": "Pinnacle", "sector": "TECHNOLOGY", "type": "PRIVATE_PROFIT", "website": "https://www.pinnacle.sh/" }, "status": "VERIFIED", "campaignId": "tf_1234567890", "keywords": { "HELP": { "message": "Pinnacle Software Development Inc.: For assistance, visit https://pinnacle.sh/support or email founders@trypinnacle.app. Msg&data rates may apply. Reply STOP to cancel." }, "OPT_IN": { "message": "Pinnacle Software Development Inc.: You're enrolled in account & security alerts. Msg&data rates may apply. Message frequency varies. Reply HELP for help, STOP to cancel. Terms: https://pinnacle.sh/terms/ Privacy: https://pinnacle.sh/privacy/", "keywords": [ "START", "SUBSCRIBE" ] } }, "links": { "privacyPolicy": "https://www.pinnacle.sh/privacy", "termsOfService": "https://www.pinnacle.sh/terms" }, "monthlyVolume": "10,000", "name": "Pinnacle's Account Notifications", "optIn": { "method": "PAPER", "url": "https://www.pinnacle.sh/opt-in", "workflowDescription": "End users opt-in when filling out the in-person intake forms where they will write their phone numbers and check a box indicating that they've opted in to messages. Link to paper form: https://www.pinnacle.sh/opt-in" }, "options": { "ageGated": false }, "productionMessageContent": "• Hi [First Name], your order #[Order ID] has shipped and will arrive [Date]. Track here: [URL]. Reply HELP for help or STOP to unsubscribe.\n• Heads up! [Friend Name] shared 3 photos. Reply VIEW to see them. Reply HELP for help or STOP to unsubscribe.\n• Hello [First Name]! I'm Pinnacle's virtual assistant. How can I help you today? Ask about order status, account updates, photo sharing, or more. Reply HELP for assistance or STOP to unsubscribe.", "useCase": { "summary": "Customers who have opted into text messages can interact with our automated SMS chatbot to receive transaction-driven notifications (order status, shipping updates, account alerts), ask support questions, share photos with friends, and manage their account details via simple, conversational text flows. All messages are transactional or interactive flows customers opt into. Users can send images (e.g., receipts) and get guided replies.", "value": "CHATBOT" } } ``` **SDK Code** ```python Toll-Free Campaign import requests url = "https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890" headers = {"PINNACLE-API-KEY": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript Toll-Free Campaign const url = 'https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890'; const options = {method: 'GET', headers: {'PINNACLE-API-KEY': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Toll-Free Campaign package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("PINNACLE-API-KEY", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Toll-Free Campaign require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["PINNACLE-API-KEY"] = '' response = http.request(request) puts response.read_body ``` ```java Toll-Free Campaign import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890") .header("PINNACLE-API-KEY", "") .asString(); ``` ```php Toll-Free Campaign request('GET', 'https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890', [ 'headers' => [ 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Toll-Free Campaign using RestSharp; var client = new RestClient("https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890"); var request = new RestRequest(Method.GET); request.AddHeader("PINNACLE-API-KEY", ""); IRestResponse response = client.Execute(request); ``` ```swift Toll-Free Campaign import Foundation let headers = ["PINNACLE-API-KEY": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/campaigns/toll-free/tf_1234567890")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers 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() ```